# 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
```
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
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.