# Production Memory Write Quality

MemPlumb v0.13.2 turns authenticated production Write Adjudications into durable quality evidence, freezes the complete eligible population into a persisted Replay Cohort Plan, and proves that the frozen population is still current before release and deployment. The strict `memory_write_quality.v1` scope answers: **does the baseline or candidate Memory Policy choose the correct write action for each adjudicated production candidate?**

This is separate from `memory_write_counterfactual.v1`. A counterfactual Run can prove that behavior changed and identify explicit safety signals, but it cannot call the change better or worse. A Write Quality Run has a production Oracle and can classify exact improvements and regressions.

## Operator workflow

1. Ingest an Event normally. Every Write Decision stores a restricted `write-decision-observation-v1` envelope with the exact candidate, current Memory read, Event time/source controls, extractor, observed Memory Policy, and Decision.
2. An evaluator-bound identity appends a Write Adjudication with the expected `create`, `update`, `noop`, or `reject` action. Adjudications are immutable revisions; a newer unverified revision never revives an older authenticated one.
3. Open **Quality -> Write Adjudications**, select an authenticated judgment, and choose **Save as Quality Case**. The CLI equivalent is:

   ```powershell
   memplumb memory-case-create `
     --decision mwd_... `
     --adjudication wadj_... `
     --idempotency-key quality-case-1 `
     --json
   ```

4. For an ad hoc investigation, open **Evaluation -> Replay Lab**, select **Write Quality**, select homogeneous Cases for one rubric, edit the candidate Memory Policy, and run. The CLI equivalent is:

   ```powershell
   memplumb replay-run `
     --case mcase_... `
     --policy policies\candidate-memory.json `
     --thresholds policies\write-quality-gate.json `
     --idempotency-key quality-run-1 `
     --json
   ```

5. Inspect exact-action and accept/reject accuracy, action confusion, error modes, per-Case improvements/regressions, safety-critical failures, and gate checks.
6. For a production release, open **Evaluation -> Cohort Plans** and create a plan with the rubric, candidate Memory Policy, thresholds, and shard size. Continue it until every shard is complete, refresh its release-evidence freshness, then bind the Plan ID to Release Artifact v12. The CLI equivalent is:

   ```powershell
   memplumb cohort-plan-create `
     --policy policies\candidate-memory.json `
     --rubric-version memory-write-v1 `
     --thresholds policies\write-quality-gate.json `
     --shard-size 200 `
     --json

   memplumb cohort-plan-resume --plan rcp_... --wait --json

   memplumb cohort-plan-check `
     --plan rcp_... `
     --maximum-age-seconds 604800 `
     --json

   memplumb release-create `
     --policy policies\candidate-memory.json `
     --write-quality-cohort-plan-id rcp_... `
     --write-quality-maximum-evidence-age-seconds 604800 `
     --output release.json
   ```

## Durable Replay Cohort Plans

`replay-cohort-plan-v1` moves population selection and sharding into the Store transaction. Plan creation chooses one database cutoff, resolves the latest authenticated consensus for the requested rubric strictly before that cutoff, rejects conflicting or stale evidence, pins each eligible Case/source manifest, sorts the population, and creates every shard and Replay Run atomically. The caller supplies no Case IDs and no cutoff, so a release operator cannot silently omit a difficult Case.

One shard contains 1-200 Cases. One Plan is bounded to 100 shards and 10,000 Cases. Every shard freezes the same baseline/candidate policy, thresholds, coverage, rubric, and execution scope. The Plan exposes counts, progress, state, opaque Run IDs, and integrity hashes through ordinary evaluation reads; member eligibility snapshots and governed sources remain Store-private.

Execution is durable. `cohort-plan-resume` advances one shard by default; `--wait` advances up to the Plan limit. Completed shard results are immutable, an expired worker is lease-fenced, and a restart resumes only unfinished work. `cohort-plan-cancel` stops pending work without converting partial evidence into release evidence. A Plan is release-ready only while its persistent status remains active and every current shard Run is completed.

## Cohort freshness and deployment validity

A completed Plan is immutable historical evidence, not an indefinite assertion that the current production population is unchanged. Memory Store Contract v19 adds `replayCohortPlanFreshness`: each call chooses one new database `checked_at` cutoff and, in the same SQLite transaction or PostgreSQL repeatable-read transaction, reconstructs the complete latest-authenticated-consensus population for the Plan rubric. It compares semantic Case references with the pinned population and reports `added_cases`, `removed_cases`, `changed_cases`, and `unchanged_cases`. Oracle conflict, source conflict, an empty current population, an over-limit population, or a Store failure blocks the check instead of treating missing evidence as fresh.

`cohort-plan-check --plan rcp_... --maximum-age-seconds 604800` runs the same check from the CLI. `GET /v1/replay-cohort-plans/{planId}/freshness?maximum_age_seconds=604800`, TypeScript `getReplayCohortPlanFreshness`, Python sync/async `get_replay_cohort_plan_freshness`, and the bilingual Cohort Plan Console expose the same public attestation. Its comparison contains counts and integrity hashes only: added, removed, changed, and unchanged Case IDs remain Store-private.

The default maximum evidence age is 604,800 seconds, or seven days. The gate passes only when the population is unchanged and the Plan cutoff has not exceeded that maximum age. The attestation binds `checked_at`, `valid_until`, remaining validity, population and comparison manifests, policy, gate checks, and an integrity hash. A shorter or longer supported maximum can be explicit, but it becomes part of the release evidence rather than an undocumented operator convention.

Release Artifact v12 loads the Plan by ID through `replayCohortPlanEvidence`, verifies the Plan/member/shard/current-Run graph and pinned source eligibility, performs the fresh Store check, and recomputes one aggregate and gate over the full population. Release construction fails closed on a stale, expired, blocked, unavailable, cancelled, invalidated, incomplete, corrupted, or tampered Plan. `release-sign` refuses an Artifact v12 whose evidence has expired; trusted deployment validation rejects it after `valid_until`; and a long-running canary rechecks validity while routing, atomically disables candidate routing with an `evidence_expired` audit transition, and falls back to stable. Re-enabling an expired candidate does not make its evidence valid.

Release Artifact v9 remains the compatible single-Run form for a complete population of at most 200 Cases. Artifact v10 remains the compatible manual batch form for 2-100 homogeneous, disjoint Runs, and v11 remains the pre-freshness Store-native Plan form. Artifacts v8-v11 remain verifiable compatibility formats; new Store-native production Cohorts use v12.

## Evidence and trust contract

Newly curated quality evidence uses `memory-case-v6`. It contains the v5 write scene, including separate policy-evaluation and Event times plus the captured current-Memory status/update time, and adds this Oracle:

```json
{
  "expected_action": "reject",
  "reason_codes": ["unsafe"],
  "safety_critical": true,
  "confidence": 0.99
}
```

Workspace, Actor, Event, Decision, Adjudication, evaluator, principal, and global Memory IDs do not enter the executable Case payload. Its separately governed `memory-write-oracle-source-v1` envelope preserves the exact Observation, authenticated evaluator provenance, revision, basis hash, judgment hash, and cutoff. Reviewer note and evidence content are deliberately omitted so `evaluation:export` cannot bypass the stronger `review:audit` boundary.

Case creation and Run/Plan population selection use database-cutoff `latest-before-auth` semantics:

- choose the latest revision for each evaluator before the cutoff;
- only then require authenticated evaluator and principal identity;
- reject an explicitly selected stale revision;
- merge current evaluators only when their judgment hashes agree; and
- fail closed when current authenticated evaluators disagree.

A Run remains immutable after completion. A later adjudication changes eligibility for a future Run but never rewrites historical results.

## Result semantics

Each lane has one quality outcome:

- `correct`: exact action matches the Oracle;
- `unexpected_write`: Oracle says `noop|reject`, policy says `create|update`;
- `missed_write`: Oracle says `create|update`, policy says `noop|reject`;
- `wrong_write_mode`: both write, but `create` and `update` differ;
- `wrong_nonwrite_mode`: both do not write, but `noop` and `reject` differ; or
- `execution_failure`: the policy could not produce a valid decision.

Per-Case baseline/candidate comparison uses the Store-compatible classifications `improved`, `regressed`, `unchanged`, and `changed`. Execution failure is counted explicitly and classified as changed rather than inventing a persistence-only classification.

Default thresholds are strict:

```json
{
  "minimum_oracle_coverage": 1,
  "minimum_candidate_action_accuracy": 1,
  "minimum_candidate_accept_reject_accuracy": 1,
  "minimum_accuracy_delta": 0,
  "maximum_regressed_cases": 0,
  "maximum_false_accepts": 0,
  "maximum_false_overwrites": 0,
  "maximum_unexpected_writes": 0,
  "maximum_missed_writes": 0,
  "maximum_wrong_write_modes": 0,
  "maximum_wrong_nonwrite_modes": 0,
  "maximum_safety_critical_errors": 0,
  "maximum_execution_failures": 0
}
```

## Coverage boundary

| Capability                            | `memory_write_quality.v1`       |
| ------------------------------------- | ------------------------------- |
| Candidate extraction                  | No; uses the captured candidate |
| Exact current Memory read             | Yes, when captured              |
| Memory Policy decision                | Yes                             |
| Authenticated production Oracle       | Yes                             |
| State reducer / committed final state | No                              |
| Historical transaction schedule       | No                              |
| Production Memory mutation            | Never                           |

This is a production write-policy quality gate, not a claim that extraction, conflict scheduling, persistence side effects, or downstream task outcomes were replayed.

## Lifecycle

Memory Store Contract v20, SQLite schema v26, and PostgreSQL migration v32 implement equivalent Case, source, cutoff, Cohort Plan, shard, event, conflict, atomic freshness, ingest idempotency fencing, and purge semantics. Workspace Snapshot v17 restores the complete Plan/member/shard/current-attempt graph across Stores and Workspaces while rebuilding Workspace-bound integrity where required. Actor export schema v14 includes Actor-linked v6 Cases, Sources, Adjudications, Runs, results, affected Cohort Plan evidence, and Actor-bound ingest claims without claim-token hashes; Actor purge removes that linked evidence so a future request or release cannot depend on deleted source evidence. Existing `memory-case-v4` quality evidence remains strictly readable and replayable with its historical field set. Release Artifact v12 is the current fresh Store-native Cohort binding; v8-v11 remain verifiable compatibility formats.