api

const (
	KeyStatusActive   = "active"
	KeyStatusInactive = "inactive"
	KeyStatusArchived = "archived"
	KeyStatusExpired  = "expired"
)

The three states an operator may set, and the fourth the server computes.

The settable set is the reference's own, quoted from the 400 its server returned to a `{"status":"deleted"}` probe: "status: Input should be 'active', 'inactive' or 'archived'" (#378). `expired` is **rendered, never stored** — storing it would need a sweeper to keep true, and a key that lapsed while the sweeper was down would keep authenticating.

const (
	// MetricDeploymentFires counts fire attempts by outcome: "created" (a run
	// row with a session), "failed" (a run row settled on a classified error,
	// sub-attributed by error.type) and "abandoned" (an unclassified failure
	// rolled the whole transaction back, so there is no run row and no error
	// type to label it with — without this outcome an infrastructure failure
	// would be invisible in the only place that counts fires). A lost claim is
	// not a fire — another replica's is — and counts nothing. Exported so the
	// test can assert the exact name.
	MetricDeploymentFires = "deployment.fires"
	// MetricDeploymentOccurrencesSkipped counts occurrences a catch-up
	// collapse passed over (§3.6) — the one number that makes a dropped
	// backlog debuggable. It rides the claim, not the tick: only the winner
	// adds, after its commit, so a rolled-back claim cannot leave a count the
	// retry would double.
	MetricDeploymentOccurrencesSkipped = "deployment.occurrences.skipped"
	// MetricDeploymentTickDuration times one whole sweep. A tick approaching
	// the tick interval is the signal that the fleet has outgrown one sweep —
	// and that deploymentFireConcurrency is wrong.
	MetricDeploymentTickDuration = "deployment.tick.duration"
)

const (
	// MetricDreamTransitions counts dream status transitions by the status
	// moved to. A closing pass moves no status and counts nothing.
	MetricDreamTransitions = "dream.transitions"
	// MetricDreamStageTurns records the model turns a running dream's current
	// stage has spent — every thread's counted (§3.3) — so the turn cap has a
	// distribution behind it rather than only a tripwire.
	MetricDreamStageTurns = "dream.stage_turns"
	// MetricDreamTickDuration times one whole sweep, the scheduler's twin.
	MetricDreamTickDuration = "dream.tick_duration"
)

const (
	MetricFileUploads       = "files.uploads"
	MetricFileUploadBytes   = "files.upload.bytes"
	MetricFileDownloadBytes = "files.download.bytes"
)

Files registry instruments (docs/plan/08_files.md observability table), mirroring the skills registry names. Attribute cardinality is bounded: outcome only — file ids belong in logs and span attributes, never in metric labels. Exported so filesmetric_test.go can assert the exact names and labels.

const (
	MetricSkillUploads       = "skills.uploads"
	MetricSkillUploadBytes   = "skills.upload.bytes"
	MetricSkillDownloadBytes = "skills.download.bytes"
)

Skill registry instruments (docs/plan/06_skills.md observability table). Attribute cardinality is bounded: outcome only — skill ids belong in logs and span attributes, never in metric labels. Exported so skillsmetric_test.go can assert the exact names and labels.

const EnvironmentKeyTTL = 365 * 24 * time.Hour

EnvironmentKeyTTL is how long an issued environment key authenticates. It matches the reference console's own year — its issuance response reports expires_in: 31536000 — and is not configurable: an operator wanting a shorter-lived credential revokes it, and the alternative, a per-key TTL, is a policy the reference does not offer and nobody has asked for.

const IssuedKeyPrefix = "sk-map-api01-"

IssuedKeyPrefix marks a management key this platform minted, beside plan 30's `sk-map-env01-` for worker credentials. It is public by construction: it is the same for every key, so showing it identifies the *kind* of credential without revealing anything about a particular one.

const (

	// MetricExpiredFilesPurged counts rows the sweep removed. Exported so the
	// test can assert the exact name; no attributes, since the only candidates
	// would be file ids.
	MetricExpiredFilesPurged = "files.expired.purged"
)

Expired-file retention (#655, plan 49 slice 2). The reference publishes both halves of what happens at expires_at: the content stops being retrievable immediately, while "Its metadata (GET /v1/files/{file_id}) remains readable for up to 30 days, with expires_at in the past". Slice 1 built the first half out of a predicate every reader composes; this is the second, and it is the only thing in this platform that removes a file nobody asked to remove.

That reverses nothing. discardUncommittedObject is about objects whose row never committed — accidents nobody can enumerate, where a sweep would have to guess what is live. An expired file is the opposite: the row names the object, and the deletion is the lifecycle the client bought at upload. That helper's argument stays true where it stands, and is now the only thing left on this side of the line (#703).

It lives beside the file routes for memoryretention.go's reason — it is written from the same facts they are — and the controlplane hosts it because that binary already holds the pool and the blob store, and a deployment whose environments are all self_hosted runs no executor.

Two things migration 0037's comment says are no longer true, and a merged migration is immutable — comments included — so the corrections live here, the same move memoryretention.go makes for 0029's. 0038's own two follow them.

It calls this plan 48, the number the plan had while slice 1 was in review; an earlier-opened PR held that number and merged first, so the plan is 49.

And it argues against an index on the ground that "a partial index over `expires_at IS NOT NULL` would cost every upload a write", which is backwards: a partial index does not index the rows its predicate excludes, so an upload with no lifetime pays nothing at all and only an expiring one pays. Migration 0038 adds that index, because the scan 0037 was willing to accept now runs once an hour on every deployment, forever.

0038 is immutable in its turn, and two things it says need the same treatment (#698). It describes the table as growing "a row per upload and a row per harvested deliverable, pruned by nothing except this sweep", and both halves are wrong about deliverables: the executor's harvest inserts them without an expires_at (internal/executor/harvest.go names id, filename, mime_type, size_bytes, downloadable, scope_type and scope_id), so this sweep never sees one — what removes them is a session delete, which takes every row scoped to the session, and the next replacing harvest, which drops the whole snapshot before writing the new one. The index still earns its place on the uploads, which do expire.

And it omits the note 0031 and 0035 both carry: migrate.go applies every pending file inside one transaction, so CREATE INDEX cannot be CONCURRENTLY. This form takes SHARE on files for the build — 0035's own wording for the same situation — so reads go on and writes wait, and they wait not for the build but for the whole migration transaction, since migrate.go commits once. On the very table 0038 argues grows without bound, that is an upgrade stall on uploads, harvests and deletes that an operator gets no warning of.

const (

	// MetricMemoryVersionsPruned counts rows the sweep removed. Exported so
	// the test can assert the exact name; no attributes, because the only
	// candidates for one would be store or memory ids.
	MetricMemoryVersionsPruned = "memory.versions.pruned"
)

Memory-version retention (#476, plan 36 scope decision 5). The reference publishes the window and withholds the count: "Versions are retained for 30 days; however, the recent versions are always kept regardless of age, so memories that change infrequently might retain history beyond 30 days." How many "recent versions" survive is stated nowhere, and no recording against the platform can reveal a server-side background policy, so the count is ours — five, registered in docs/DIVERGENCES.md.

It lives beside the memory routes rather than in a package of its own because it is the same three facts they are written from: the head pointer is memories.memory_version_id, a version's lineage is (memory_store_id, memory_id), and neither is a foreign key. The controlplane hosts it because that binary already holds the pool and serves every memory route — a deployment whose environments are all self_hosted runs no executor at all.

The sweep leans on migration 0029's memory_versions_memory_idx (memory_store_id, memory_id, created_at DESC, id DESC), which makes the per-candidate "newest keep" lookup an index-only scan of exactly keep rows. That index's own comment predates this file and calls the history one "nothing ever prunes"; a merged migration is immutable, so the fact lives here instead. Narrowing or dropping it would turn a seconds-long sweep into one that walks a whole store's history per candidate row.

const MetricSessionResources = "session.resources"

MetricSessionResources counts session resource mutations (create-attach, add, delete, token rotation) by outcome. Outcome-only labels: session/resource/file ids ride the structured logs, never the metric (plan decision 9). Exported so the integration test can assert the name and labels.