# Deepsleep SPEC

Status: draft v0

## Purpose

Deepsleep is a Lifeloop-side ingestion client for CCD-volunteered continuity
artifacts. It captures those artifacts into a durable corpus so later offline
jobs can build higher-level artifacts.

The v0 slice is ingestion only. Hippocampus is the durable consumer; later
offline workers read the corpus and decide which generated artifacts are useful.

## Scope

Deepsleep v0 ingests existing CCD source artifacts. It does not ingest
generated projections, summaries, or model-produced synthesis artifacts. Those
need a producer-specific spec before Deepsleep accepts them as source material.

## Input

The v0 producer is CCD.

A Deepsleep ingest request carries one CCD artifact:

```text
artifact_kind: checkpoint | handover | debug-export
artifact_id
thread_id
spin_id?
checkpoint_id?
created_at
media_type
body | file_path
metadata
```

Metadata can include:

```text
profile_id
project_root
receipt_id
source_event
```

CCD chooses which continuity artifacts to feed. The initial set is checkpoint,
handover, and debug-export artifacts.

Canonical artifact bytes are the resolved artifact body bytes:

```text
body
```

`media_type` and envelope metadata are registered as Hippocampus metadata. They
are not part of the canonical artifact bytes.

## Canonical URI

Deepsleep uses a local source-identity URI:

```text
ccd://thread/<thread_id>/<artifact_kind>/<artifact_id>
```

The URI is an identity key, not a dereferenceable transport URL. `thread_id`,
`artifact_kind`, and `artifact_id` are non-empty URI path segments. Values that
are not already path-safe are percent-encoded before URI construction.

## Registration Flow

Deepsleep registers one file-backed source item:

1. Resolve `body` or read `file_path`.
2. Build canonical artifact bytes from the artifact content.
3. Compute `content_hash` from canonical artifact bytes.
4. Build `canonical_uri`.
5. Probe Hippocampus by `canonical_uri`.
6. Return `duplicate` when the existing item has the same `content_hash`.
7. Return `conflict` when the existing item has a different `content_hash`.
8. Write the primary artifact under the Hippocampus root.
9. Compute primary artifact `byte_size` and `sha256`.
10. Allocate `slug` with `MakeUniqueSlug`.
11. Call `Register`.

If `Register` returns `ErrSlugCollision`, Deepsleep allocates a new slug from
the same slug base and retries registration at most two more times. If all
three attempts collide, ingestion returns `failed`.

## Hippocampus Registration

Deepsleep stores the CCD artifact in Hippocampus.

Registration mapping:

```text
slug_base: deepsleep-ccd-<thread_id>-<artifact_kind>-<artifact_id>
slug: MakeUniqueSlug(slug_base)
source_kind: ccd-continuity-artifact
collections: profile:<profile_id>, producer:ccd
title: ccd <artifact_kind> <artifact_id>
canonical_uri: ccd://thread/<thread_id>/<artifact_kind>/<artifact_id>
content_hash: sha256(canonical artifact bytes)
ingestion_source: ccd
extraction_method: deepsleep-ingest
extraction_version: v0
source_created_at: <created_at>
metadata: ingest request metadata plus artifact kind and media type
```

Primary artifact:

```text
artifact_role: primary-source
rel_path: raw/deepsleep/ccd/<thread_id>/<artifact_kind>/<artifact_id>.<ext>
mime_type: <media_type>
byte_size: byte length of primary artifact file
sha256: sha256(canonical artifact bytes)
record_origin: source
```

`<ext>` is derived from `media_type`: `json` for `application/json`, `md` for
Markdown, `txt` for `text/plain`, and `bin` otherwise.

When the artifact content is already plain text or Markdown, Deepsleep can also
register an `extracted-text` artifact:

```text
artifact_role: extracted-text
rel_path: raw/deepsleep/ccd/<thread_id>/<artifact_kind>/<artifact_id>.md
mime_type: text/markdown
byte_size: byte length of extracted-text file
sha256: sha256(extracted-text bytes)
record_origin: source
extraction.method: thalamus.text-markdown
```

## Thalamus Enrichment

Thalamus is used when an artifact benefits from deterministic extraction.

Initial use:

- run `TextMarkdownExtractor` for UTF-8 `text/plain` and Markdown artifact
  content;
- persist `extracted.md` as the Hippocampus `extracted-text` artifact;
- copy Thalamus diagnostics and source-map metadata onto the artifact.

Structured JSON remains valuable as the `primary-source` artifact. A stable
Markdown projection can be added when search quality needs it.

## Deduplication And Conflicts

`canonical_uri` is the canonical identity. It includes `artifact_id`, which CCD
must keep stable for write-once source artifacts. Deepsleep computes the content
hash over canonical artifact bytes.

On ingest:

1. Probe Hippocampus by `canonical_uri`.
2. Reuse the existing source item when `content_hash` also matches.
3. Report `conflict` when the canonical URI repeats with changed content.
4. Register a new source item when the artifact has a new canonical URI.

## Ingest Result

Each ingestion attempt returns a small result to the caller or operator log:

```text
status: registered | duplicate | conflict | failed
source_item_id?
artifact_ids[]
content_hash
diagnostics[]
```

Failures are operational: malformed ingest request, missing artifact content,
unreadable artifact path, repeated slug collision, Hippocampus registration
failure, or Thalamus extraction failure for optional enrichment.

## Later Work

Generated artifacts and project-scoped collection keys are covered by later
specs.
