@llblab/pi-state-flow 0.28.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -18,7 +18,7 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
18
18
 
19
19
  ## Publication and lifecycle
20
20
 
21
- - Keep one Strategy/Tactics model/API across metadata3 core cohorts and metadata4 retained-module cohorts. Translate declared legacy v1/v2 cohorts before filtering; reject raw collisions and target-format retired roots. Only owned semantic acceptance may convert, after verified exact-byte backup and CAS; inspection and runtime-only mode persistence cannot. Preserve revisions/causal identities and opaque recovery bytes; semantic decoding must reject invalid UTF-8. Quiesce unsupported old writers. See [migration and backup](docs/usage.md#moving-a-store-and-supported-formats).
21
+ - Keep one Strategy/Tactics model/API across metadata3 core cohorts and metadata4 retained-module cohorts. Since 1.0.0, retired metadata v1/v2 cohorts are refused with an actionable message instead of translated, and `RetiredSemanticFormatError` keeps self-healing from treating a known old format as corruption; target-format retired roots stay reserved. Only owned semantic acceptance may convert or upgrade (lifecycle v1, module descriptors), after verified exact-byte backup and CAS; inspection and runtime-only mode persistence cannot. Preserve revisions/causal identities and opaque recovery bytes; semantic decoding must reject invalid UTF-8. Quiesce unsupported old writers. See [migration and backup](docs/usage.md#moving-a-store-and-supported-formats).
22
22
  - Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority. Unrecoverable owners self-heal only through `lib/healing.ts`: after a failed acquisition, under store exclusion and never behind a live writer, quarantine the owner's exact bytes privately, reset only that owner to wholly absent and announce it to both operator and model; never silently. Filesystem, lock, cancellation and foreign-identity failures stay fail-closed. Never repair through other ad-hoc writes. See [self-healing](docs/filesystem-recovery.md#self-healing). See [storage recovery](docs/usage.md#storage-and-recovery) and [transaction rule](docs/filesystem-recovery.md#transaction-rule).
23
23
  - Keep exact regular-file, byte-CAS and lock-serialized publication with cancelable waits, single-use callback-scoped capabilities and guarded rollback. Never hold exclusion across inference, source acquisition or Git; do not steal interrupted locks, claim kernel-atomic multi-file publication or promise power-loss durability. See [asynchronous transaction](docs/architecture.md#asynchronous-storage-transaction) and [durability boundary](docs/filesystem-recovery.md#power-loss-durability).
24
24
  - Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. Memory never depends on the Pi step: it is the current same-session JSON state, advanced only by accepted `state_flow_patch`/lifecycle publications. Startup, reload, resume and tree navigation validate and accept current same-session memory; native checkpoints supply only mode and run lifecycle, never a revision to rewind to. A fork copies its parent's current memory into a fresh child owner. Never substitute Git, foreign or fabricated memory; missing or unreadable current files restart only the affected owner from visible empty memory through self-healing, never silently. Only accepted candidates install cache, checkpoint and mode. Memory that stays unavailable after healing (unhealable causes) under Active retains Active policy, visibly reports `active (blocked)` and fences live inference through public Abort until accepted Active/Passive or explicit Off; never silently expose native history or an inactive indicator as fallback. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [fork contract](docs/fork-contract.md).
package/BACKLOG.md CHANGED
@@ -11,8 +11,12 @@ These remain outstanding separately from release-local 0.27.2 acceptance; neithe
11
11
  - [ ] **Live-model semantic-memory comparison — authorization-gated, not run.** Use the [existing corpus, runner and rubric](docs/semantic-memory-evaluation.md), preserved baseline source and actual target digests. Include feasible flat-versus-scoped errors/retries/quality/cost comparisons; disclose provider/model drift and unsupported comparisons. Unblocker: an explicitly authorized normal inference route, pinned model/provider/reasoning and bounded request/token/time limits. Do not scrape/copy credentials or relabel faux calibration as model evidence.
12
12
  - [ ] **Installed-client compatibility smoke — operator/environment-gated, not established by CI.** With explicit installation/reload authority and an isolated store/session, check the intended TUI/Telegram client's mode controls, captured selection, inspection and unavailable-owner presentation against [compatibility boundaries](docs/compatibility.md). Record exact client/SDK/package identities and observed results; scripted/native fixtures do not certify live reachability, rendering or every newer SDK.
13
13
 
14
+ ## Compatibility window
15
+
16
+ - The `contract`/`working` converter was removed in 1.0.0 and both retired root names stay reserved. A store still in metadata v1/v2 must be opened once with a State Flow 0.x release, where owned Active/Start acceptance converts it after a verified backup. The operator's active store was inventoried before the release and contained no legacy cohorts.
17
+
14
18
  ## Scope and authorization limits
15
19
 
16
- - Preserve legacy conversion and retired-root reservations throughout State Flow 0.x, with the settled 1.0.0 cutoff and explicit unsupported-version refusal; see the [migration support policy](docs/semantic-compatibility-decision.md#implementation-direction-and-reserved-names). No converter-removal or new migration task is implied.
20
+ - Preserve explicit unsupported-version refusal and retired-root reservations; see the [migration support policy](docs/semantic-compatibility-decision.md#implementation-direction-and-reserved-names). No further converter, downgrade or live-store repair is implied.
17
21
  - New planes/scopes, changed public module semantics, dynamic loading/sandboxing, background inference, storage formats, speculative performance work and broad redesign remain outside consolidation. They are not dormant implementation promises.
18
22
  - Live-store conversion and all other release/rollout actions require their normal explicit authorization. Temporary evidence belongs under ignored `temp/`, not a parallel task queue.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,12 @@
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 1.0.0: Automatic Recovery, No Legacy Conversion
8
+
9
+ - `Visible self-healing`: An owner whose canonical files cannot be decoded, or a boundary whose session memory is missing, no longer blocks forever. After a failed acquisition, State Flow quarantines the exact bytes privately in `<store>-quarantine/`, resets only that owner to empty memory, retries once and tells the operator, the model and the local log. Healthy owners stay untouched; filesystem, lock, cancellation and foreign-identity failures stay fail-closed.
10
+ - `Retired formats refused`: The temporary `contract`/`working` converter is gone. A store still in metadata v1/v2 now fails with an actionable message instead of being converted; open it once with a State Flow 0.x release first. Both retired root names stay reserved, and self-healing never resets a known old format.
11
+ - `Empty stores read as empty`: A branch without accepted memory reads absent shared values as `null` instead of an unavailable runtime; an uncreated Session says the first accepted patch creates it.
12
+
7
13
  ## 0.28.0: Visible Self-Healing Memory
8
14
 
9
15
  - `Visible self-healing`: An owner whose canonical files cannot be decoded, or a boundary whose session memory is missing, no longer blocks forever. After a failed acquisition, State Flow quarantines the exact bytes privately in `<store>-quarantine/`, resets only that owner to empty memory, retries once and tells the operator, the model and the local log. Healthy owners stay untouched; filesystem, lock, cancellation and foreign-identity failures stay fail-closed.
@@ -4,7 +4,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
4
4
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
5
5
  import { parseArtifactProvenanceRegistry, serializeArtifactProvenanceRegistry, } from "./artifact.js";
6
6
  import { MAX_HISTORY_LIMIT } from "./history.js";
7
- import { prepareSerializedScopeMigration } from "./migration.js";
7
+ import { prepareSerializedScopeMigration, refuseRetiredSemanticVersion } from "./migration.js";
8
8
  import { canonicalJson, isJsonValue, isObject } from "./json.js";
9
9
  import { validateScopeStream, validateTemporalState } from "./temporal.js";
10
10
  import { assertRetainedModules, validateRetainedModules } from "./semantic-module.js";
@@ -46,7 +46,7 @@ export function serializeScopeStream(stream, scope, cwdIdentity) {
46
46
  };
47
47
  }
48
48
  function isSupportedScopeMetadataVersion(version) {
49
- return version === 1 || version === 2 || version === 3 || version === 4;
49
+ return version === 3 || version === 4;
50
50
  }
51
51
  /** Distinguish a wholly absent semantic cohort from partial or malformed surviving authority. */
52
52
  export function classifyScopeStream(checkpointSource, patchesSource, scope, expectedCwd, metaSource) {
@@ -77,6 +77,8 @@ export function classifyScopeStream(checkpointSource, patchesSource, scope, expe
77
77
  throw new Error(`Unsupported State Flow ${scope} storage format`);
78
78
  }
79
79
  const metadata = parseMetadataDocument(metaSource, `State Flow ${scope} metadata`);
80
+ if (metadata.version === 1 || metadata.version === 2)
81
+ refuseRetiredSemanticVersion(metadata.version);
80
82
  if (!isSupportedScopeMetadataVersion(metadata.version))
81
83
  throw new Error(`Unsupported State Flow ${scope} metadata version`);
82
84
  // In Unicode mode this range matches lone UTF-16 surrogates, not valid pairs or JSON escapes.
@@ -2362,6 +2362,9 @@ export default function stateFlowExtension(pi, options = {}) {
2362
2362
  return { compaction: result };
2363
2363
  });
2364
2364
  pi.on("agent_before_settle", async (_event, ctx) => {
2365
+ // Passive has no response reconciliation: its settled run is the accepted turn for already published patches.
2366
+ if (!shuttingDown && snapshot.config.mode === "passive" && memoryToolsAvailable())
2367
+ backup.markTurnAccepted();
2365
2368
  if (shuttingDown || !memoryToolsAvailable() || !backup.takeSettledTurn())
2366
2369
  return;
2367
2370
  const operationSignal = ctx.signal;
@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
4
4
  import { constants, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
5
  import { basename, dirname, relative, resolve } from "node:path";
6
6
  import { canonicalJson } from "./json.js";
7
+ import { RetiredSemanticFormatError } from "./migration.js";
7
8
  import { sessionRuntimePaths, temporalScopePaths } from "./durable.js";
8
9
  import { captureScopeSelection } from "./selection.js";
9
10
  import { RevisionUnavailableError } from "./snapshot.js";
@@ -15,7 +16,7 @@ import { assertStorageDirectory, PublicationBusyError, withStorageTransaction }
15
16
  export function isHealableCorruption(error) {
16
17
  if (!(error instanceof Error))
17
18
  return false;
18
- if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError)
19
+ if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError || error instanceof RetiredSemanticFormatError)
19
20
  return false;
20
21
  if (error.name === "AbortError")
21
22
  return false;
@@ -1,10 +1,9 @@
1
- import { type JsonObject } from "./json.ts";
2
1
  import { type RetainedModules } from "./semantic-module.ts";
3
2
  import { type StateScope } from "./state.ts";
4
3
  import { type ScopeStream } from "./temporal.ts";
5
- /** Owns temporary pure semantic-dialect conversion; excludes I/O, publication, backup and lifecycle authority. */
4
+ /** Owns the pure v3/v4 semantic codec and module-descriptor upgrade; excludes I/O, publication, backup and lifecycle authority. */
6
5
  export interface SemanticMigrationCandidate {
7
- sourceVersion: 1 | 2 | 3 | 4;
6
+ sourceVersion: 3 | 4;
8
7
  targetVersion: 3 | 4;
9
8
  /** A format conversion is not an authored semantic transition or revision. */
10
9
  requiresConversion: boolean;
@@ -21,8 +20,11 @@ export interface SerializedSemanticMigrationCandidate extends SemanticMigrationC
21
20
  basis: Record<ScopeMigrationFile, MigrationByteReceipt>;
22
21
  target: Record<ScopeMigrationFile, string>;
23
22
  }
24
- /** Translate a raw legacy checkpoint or replay patch before any known-field filtering. */
25
- export declare function translateLegacySemanticObject(value: unknown): JsonObject;
23
+ /** A known retired format, not corruption: self-healing must never reset it. */
24
+ export declare class RetiredSemanticFormatError extends Error {
25
+ }
26
+ /** State Flow 1.0.0 ended the temporary contract/working conversion window; refusal stays explicit. */
27
+ export declare function refuseRetiredSemanticVersion(version: unknown): never;
26
28
  /** Build a detached target candidate; publication still belongs to the guarded storage transaction. */
27
29
  export declare function prepareSemanticMigration(value: unknown, scope: StateScope, sourceVersion: number, historyLimit?: number, targetModules?: RetainedModules): SemanticMigrationCandidate;
28
30
  /** Decode a complete raw owner cohort before filtering; never load files, normalize authority or publish. */
@@ -3,62 +3,21 @@ import { resolve } from "node:path";
3
3
  import { parseArtifactProvenanceRegistry } from "./artifact.js";
4
4
  import { MAX_HISTORY_LIMIT } from "./history.js";
5
5
  import { canonicalJson, isJsonValue, isObject, validatePatch } from "./json.js";
6
- import { parseStateReadPath, parseValuePath } from "./query.js";
7
6
  import { assertRetainedModules, validateRetainedModules } from "./semantic-module.js";
8
7
  import { assertNoRetiredSemanticPlanes } from "./state.js";
9
8
  import { validateScopeStream } from "./temporal.js";
10
- const LEGACY_PLANES = new Map([["contract", "strategy"], ["working", "tactics"]]);
11
- const LEGACY_SEMANTIC_PLANES = new Set(["intents", "contract", "working", "artifacts", "response", "lazy"]);
12
- const LEGACY_LOCATOR = /^(?:((?:effective|global|cwd|session)(?:\[\d+\])?(?:\.patches(?:\[\d+\])?)?)\.)?(contract|working)(?=$|\.|\[)/;
13
- const MARKED_LOCATOR = /(?<![\p{L}\p{N}_$.[\]:/\\-])\$([\p{L}\p{N}_$.[\]:-]+)(?![\p{L}\p{N}_$.[\]:/\\-])/gu;
14
- function translateLocator(path) {
15
- const match = LEGACY_LOCATOR.exec(path);
16
- if (!match)
17
- return path;
18
- const [, prefix, plane] = match;
19
- const suffix = path.slice(match[0].length);
20
- try {
21
- if (prefix)
22
- parseStateReadPath(prefix, MAX_HISTORY_LIMIT);
23
- // The unchanged lazy root lets the shared parser validate selectors after legacy names retire.
24
- parseValuePath(`lazy${suffix}`);
25
- }
26
- catch {
27
- return path;
28
- }
29
- return `${prefix ? `${prefix}.` : ""}${LEGACY_PLANES.get(plane)}${suffix}`;
9
+ /** A known retired format, not corruption: self-healing must never reset it. */
10
+ export class RetiredSemanticFormatError extends Error {
30
11
  }
31
- function translateReferences(value) {
32
- if (typeof value === "string")
33
- return value.replace(MARKED_LOCATOR, (_token, path) => `$${translateLocator(path)}`);
34
- if (Array.isArray(value))
35
- return value.map(translateReferences);
36
- if (!isObject(value))
37
- return value;
38
- return Object.fromEntries(Object.entries(value).map(([key, child]) => [key,
39
- key === "$ref" && typeof child === "string" ? translateLocator(child) : translateReferences(child)]));
40
- }
41
- function translateArtifacts(value) {
42
- if (!isObject(value))
43
- return translateReferences(value);
44
- return Object.fromEntries(Object.entries(value).map(([path, card]) => [path, !isObject(card) ? translateReferences(card)
45
- : Object.fromEntries(Object.entries(card).map(([key, child]) => [key,
46
- // Retired embedded provenance is evidence, never a semantic reference namespace.
47
- ["hash", "compiler", "compiled_at"].includes(key) ? structuredClone(child) : translateReferences(child)]))]));
48
- }
49
- /** Translate a raw legacy checkpoint or replay patch before any known-field filtering. */
50
- export function translateLegacySemanticObject(value) {
51
- validatePatch(value);
52
- for (const plane of LEGACY_PLANES.values()) {
53
- if (Object.hasOwn(value, plane))
54
- throw new Error(`Target State Flow semantic plane in legacy format: ${plane}`);
55
- }
56
- return Object.fromEntries(Object.entries(value).map(([key, child]) => [LEGACY_PLANES.get(key) ?? key,
57
- key === "artifacts" ? translateArtifacts(child) : LEGACY_SEMANTIC_PLANES.has(key) ? translateReferences(child) : structuredClone(child)]));
12
+ /** State Flow 1.0.0 ended the temporary contract/working conversion window; refusal stays explicit. */
13
+ export function refuseRetiredSemanticVersion(version) {
14
+ throw new RetiredSemanticFormatError(`Unsupported State Flow semantic metadata version ${String(version)}: legacy contract/working memory is no longer converted since State Flow 1.0.0; open it once with State Flow 0.x to convert it`);
58
15
  }
59
16
  /** Build a detached target candidate; publication still belongs to the guarded storage transaction. */
60
17
  export function prepareSemanticMigration(value, scope, sourceVersion, historyLimit = MAX_HISTORY_LIMIT, targetModules) {
61
- if (sourceVersion !== 1 && sourceVersion !== 2 && sourceVersion !== 3 && sourceVersion !== 4)
18
+ if (sourceVersion === 1 || sourceVersion === 2)
19
+ refuseRetiredSemanticVersion(sourceVersion);
20
+ if (sourceVersion !== 3 && sourceVersion !== 4)
62
21
  throw new Error("Unsupported State Flow migration source version");
63
22
  validatePatch(value);
64
23
  if (!isObject(value.checkpoint) || !Array.isArray(value.patches))
@@ -76,8 +35,6 @@ export function prepareSemanticMigration(value, scope, sourceVersion, historyLim
76
35
  if (sourceVersion !== 4 && targetModules !== undefined && isObject(state)
77
36
  && Object.keys(state).some(key => key.startsWith("x_")))
78
37
  throw new Error("Legacy State Flow external namespace collision");
79
- if (sourceVersion < 3)
80
- return translateLegacySemanticObject(state);
81
38
  validatePatch(state);
82
39
  assertNoRetiredSemanticPlanes(state);
83
40
  return structuredClone(state);
@@ -136,7 +93,9 @@ export function prepareSerializedScopeMigration(sources, scope, expectedCwd, tar
136
93
  if (!isObject(metadata))
137
94
  throw new Error("Invalid State Flow migration metadata");
138
95
  const version = metadata.version;
139
- if (version !== 1 && version !== 2 && version !== 3 && version !== 4)
96
+ if (version === 1 || version === 2)
97
+ refuseRetiredSemanticVersion(version);
98
+ if (version !== 3 && version !== 4)
140
99
  throw new Error("Unsupported State Flow migration source version");
141
100
  if (version === 4)
142
101
  validateRetainedModules(metadata.modules);
@@ -159,7 +118,7 @@ export function prepareSerializedScopeMigration(sources, scope, expectedCwd, tar
159
118
  if (!isObject(temporal) || !Object.hasOwn(temporal, "checkpoint") || !Array.isArray(temporal.patches)) {
160
119
  throw new Error("Invalid State Flow migration temporal metadata");
161
120
  }
162
- if (version >= 3 && !Object.hasOwn(temporal, "revision"))
121
+ if (!Object.hasOwn(temporal, "revision"))
163
122
  throw new Error("State Flow target migration metadata requires a revision");
164
123
  const checkpointText = decodeMigrationText(basis.checkpoint.bytes, "checkpoint");
165
124
  const patchesText = decodeMigrationText(basis.patches.bytes, "tail");
@@ -171,7 +130,7 @@ export function prepareSerializedScopeMigration(sources, scope, expectedCwd, tar
171
130
  throw new Error("State Flow migration metadata does not match its semantic tail");
172
131
  const candidate = prepareSemanticMigration({
173
132
  ...(version === 4 ? { modules: metadata.modules } : {}),
174
- revision: temporal.revision === undefined ? patches.length : temporal.revision,
133
+ revision: temporal.revision,
175
134
  checkpoint: { through: temporal.checkpoint, state: checkpoint },
176
135
  patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
177
136
  }, scope, version, MAX_HISTORY_LIMIT, targetModules);
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.28.0",
3
+ "version": "1.0.0",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
@@ -26,9 +26,9 @@ Since 0.27.6 the advertised tools are `state_flow_read` and `state_flow_patch`.
26
26
 
27
27
  ## Canonical scope format admission
28
28
 
29
- Core-only canonical scope metadata remains **version 3**, with `strategy` and `tactics` fields. The implemented **version 4** codec additionally retains external object-plane descriptors and opaque values independently of loaded definitions; absent internal `modules` metadata keeps existing v3 output. Declared legacy versions **1/2** translate before known-field filtering. Target-format `contract`/`working` roots reject; nested domain keys remain ordinary JSON. Unsupported versions fail closed. These scope versions are distinct from selection-aware Session lifecycle v2 and public module API v1; supported legacy lifecycle-v1 admission retains its complete-cohort proof requirements. External-root tools, captured Active/Passive context and Active producers shipped in 0.27.0; see the [public module boundary](public-module-contract.md).
29
+ Core-only canonical scope metadata remains **version 3**, with `strategy` and `tactics` fields. The implemented **version 4** codec additionally retains external object-plane descriptors and opaque values independently of loaded definitions; absent internal `modules` metadata keeps existing v3 output. Since **1.0.0**, retired versions **1/2** are refused explicitly instead of translated, and target-format `contract`/`working` roots stay reserved; nested domain keys remain ordinary JSON. Unsupported versions fail closed. These scope versions are distinct from selection-aware Session lifecycle v2 and public module API v1; supported legacy lifecycle-v1 admission retains its complete-cohort proof requirements. External-root tools, captured Active/Passive context and Active producers shipped in 0.27.0; see the [public module boundary](public-module-contract.md).
30
30
 
31
- Legacy inspection is observational. Owned semantic acceptance may convert only admitted owner scopes, after complete target-cohort/identity validation, exact source CAS and a verified private backup outside canonical authority. Missing legacy revisions credit retained records only; conversion itself adds no learning transition. Opaque capture/rollback preserves arbitrary original bytes while semantic interpretation requires valid UTF-8. See [migration proof and support limits](semantic-compatibility-decision.md#guarded-publication-and-support-boundary) and [backup/recovery guidance](usage.md#moving-a-store-and-supported-formats).
31
+ A retired cohort needs one State Flow 0.x Active/Start acceptance before upgrading. Owned acceptance there converted only admitted owner scopes, after complete target-cohort/identity validation, exact source CAS and a verified private backup outside canonical authority; conversion added no learning transition. Descriptor upgrades and legacy lifecycle conversion still follow that same guarded path. Opaque capture/rollback preserves arbitrary original bytes while semantic interpretation requires valid UTF-8. See [migration proof and support limits](semantic-compatibility-decision.md#guarded-publication-and-support-boundary) and [backup/recovery guidance](usage.md#moving-a-store-and-supported-formats).
32
32
 
33
33
  This breaking semantic API/storage change shipped in **0.27.0** and is retained in **0.27.1**. Existing exported names remain where applicable but their fields, callbacks, schemas and paths use Strategy/Tactics; no permanent old-field aliases are provided. Upgrade/quiesce old consumers before deployment: already-deployed unsafe low-level callers cannot be universally fenced. No active store was operated on during development.
34
34
 
@@ -16,20 +16,18 @@ Evidence baseline: package 0.26.5, commit `4494fee9da8258cdf5f02c42672a0eb9866a5
16
16
  - **One-time and recoverable:** Produce a detached, collision-checked conversion candidate, translate recognized semantic references, validate all retained replay boundaries, and publish checkpoint/tail/metadata together using existing exclusion/CAS/rollback. The accepted target version makes repeat acquisition idempotent. Ordinary inspection and history reads do not become migration writes; source discovery alone grants no publication authority.
17
17
  - **Fail closed:** Reject coexisting old/new root names for explicit reconciliation, unsupported versions, malformed replay, partial evidence and occupied/conflicting destinations. Do not silently merge or destroy evidence. Already-recorded ownership cascades do not run a second time.
18
18
  - **Retirement insight:** Removing the temporary converter does not remove version admission. An unsupported old store must fail explicitly after retirement, not be reinterpreted as newly available user-defined planes.
19
- - **Settled support timing:** These are State Flow package versions. Throughout **0.x**, retain legacy `contract`/`working` conversion and reserve those retired owner-root names. Beginning **1.0.0**, that temporary legacy support and reservation window ends; explicit unsupported-version refusal remains. There is no separate **1.1** deadline. Released **0.27.0/0.27.1** retain the converter and reservations; 0.27.2 consolidation preserves that policy. This policy does not authorize immediate code removal, release, working-store conversion or automatic registration of new planes. Package release numbers are not persisted schema identifiers.
19
+ - **Settled support timing, now applied:** The temporary `contract`/`working` converter was retained throughout **0.x** and removed in **1.0.0**. Retired owner-root names stay reserved; explicit unsupported-version refusal remains and now covers versions 1/2 with an actionable message. Recovering a retired store requires one State Flow 0.x Active/Start acceptance first. Package release numbers are not persisted schema identifiers.
20
20
  - **Operational boundary:** Version checks in this checkout cannot retrofit already-deployed old low-level callers. Upgrade/quiesce unsupported writers before converting shared cohorts; development only exercises temporary stores. No implicit active-store conversion, downgrade or release publication.
21
21
 
22
22
  ## Pure conversion boundary
23
23
 
24
- `lib/migration.ts` owns the temporary, side-effect-free conversion candidate. `prepareSemanticMigration` requires an explicit supported source metadata version. Versions 1/2 translate to target **3**; already-target v3/v4 candidates are validated and detached without another semantic rename. Admitted retained-module descriptors select target **4**, including the guarded first external-root admission; v4 descriptors cannot be dropped or silently changed. These are scope-format identifiers, independent of package SemVer and Pi SDK versions; native readers expose one Strategy/Tactics dialect. This module is not exported from the package root and grants no file/publication authority.
24
+ `lib/migration.ts` owns the side-effect-free semantic codec. `prepareSemanticMigration` admits only metadata versions 3/4; retired versions 1/2 throw `RetiredSemanticFormatError`, which self-healing treats as a known old format rather than corruption. Admission and refusal stay separate: an unsupported old store fails explicitly and is never reinterpreted as user-defined planes. Admitted retained-module descriptors select target **4**, including the guarded first external-root admission; v4 descriptors cannot be dropped or silently changed. These are scope-format identifiers, independent of package SemVer and Pi SDK versions; native readers expose one Strategy/Tactics dialect. This module is not exported from the package root and grants no file/publication authority.
25
25
 
26
- - Root `contract`/`working` become `strategy`/`tactics`; sparse absence, empty legacy branches, patch deletion markers, arrays, ordinary nested keys and opaque unknown root data remain intact. Any target root name in declared legacy data rejects, even without an old sibling. Target candidates reject retired roots in checkpoints and patches, including deletion attempts.
27
- - Recognized exact structured `$ref` locators and deliberate textual `$path` tokens translate only the plane position. Scope, historical selectors, array/range spelling and ownership classification remain unchanged. The query domain supplies shared selector syntax validation without target lookup. Unsupported/unparseable locators, unmarked prose and resource paths stay unchanged; no reference is hydrated or granted authority.
28
- - Artifact registry keys and retained embedded `hash`/`compiler`/`compiled_at` evidence stay opaque. Eligible semantic description/compilation references may translate, but provenance is not a semantic-reference namespace. Hidden provenance metadata is outside this stream candidate and is preserved unchanged by the serialized preflight below.
26
+ - Retired root `contract`/`working` stay reserved: current checkpoints and patches reject them, including deletion attempts, and they are never reinterpreted as external planes.
29
27
  - Candidate construction validates replay, preserves every transition identity/parent/position and owner revision, and returns detached data. It does not normalize empties, invent a transition, rerun ownership cascades, fold history or write a store.
30
- - Legacy objects translate before target semantic validation, with extra envelope fields retained until strict validation. The temporary reverse-validation bridge is removed. Malformed legacy/target fixtures ensure that conversion cannot sanitize an invalid envelope into acceptance.
28
+ - Artifact registry keys and retained embedded `hash`/`compiler`/`compiled_at` evidence stay opaque; provenance is not a semantic-reference namespace and is preserved unchanged by the serialized preflight.
31
29
 
32
- `tests/migration.test.ts` proves root reservation/collision handling, locator boundaries and opaque provenance, candidate detachment/idempotence, every retained owner boundary and aligned effective overlay at limits 0/1/7/100, and malformed replay refusal. These are deterministic conversion proofs, not interruption/CAS/backup tests or a live-model evaluation.
30
+ `tests/migration.test.ts` proves explicit retired-version refusal, root reservation, detached exact-byte receipts, module-descriptor upgrade with collision refusal, and malformed replay rejection. These are deterministic codec proofs, not interruption/CAS/backup tests or a live-model evaluation.
33
31
 
34
32
  ## Serialized owner-cohort preflight
35
33
 
package/docs/usage.md CHANGED
@@ -352,14 +352,15 @@ Commit or push failure is diagnostic-only; repeated push failures warn once per
352
352
 
353
353
  **Supported formats.** State Flow accepts only canonical checkpoint/tail files, temporal metadata and the separate session config/runtime contract.
354
354
 
355
- **Why files can still contain `contract`/`working` after an update.** Installing or reloading the package is not a whole-store migration. Legacy reads translate those roots to `strategy`/`tactics` in memory; disk conversion occurs only when an owned semantic transaction accepts the participating cohort. Off, inspection and runtime-only mode persistence do not perform it. Unselected owners and untouched historical sessions remain in their supported legacy format until their own acceptance; accepting one session never scans or upgrades every project/session. To convert an existing cohort, first quiesce old writers, then explicitly accept its current memory with Active/Start using the upgraded code. Keep the verified migration backup; do not rename JSON keys manually or reopen old writers against converted files.
355
+ **Retired `contract`/`working` cohorts are refused, not converted.** State Flow 1.0.0 ended the temporary conversion window. A scope whose metadata still declares version 1 or 2 now fails with an explicit message naming the scope: open the store once with a State Flow 0.x release so its owned Active/Start acceptance converts it, then upgrade. Renaming JSON keys by hand is never supported.
356
356
 
357
- - Scope metadata versions 1/2 remain readable through explicit `contract → strategy`, `working → tactics` translation before field filtering. Current/historical tools expose only the target dialect; retired root writes reject rather than becoming aliases. Legacy missing revisions credit only retained tail records.
358
- - Core-only writes use scope metadata v3; retained external-module descriptors select v4. Both use Strategy/Tactics. On owned semantic acceptance, supported legacy/descriptor upgrades use the same backup, lock/CAS and rollback checks without advancing revisions/causal identities for representation alone. Ordinary inspection and runtime-only mode persistence do not convert files. Upgrade/quiesce all writers before enabling the new code: already-deployed low-level readers cannot be universally fenced by a format number.
357
+ - Retired root names stay reserved: `contract` and `working` written into a current checkpoint or patch reject, including deletion attempts, and are never reinterpreted as user-defined planes.
358
+ - Self-healing never applies to this refusal. A retired cohort is a known old format, not corruption, so its bytes are left exactly as they are.
359
+ - Core-only writes use scope metadata v3; retained external-module descriptors select v4. Both use Strategy/Tactics. On owned semantic acceptance, descriptor upgrades and legacy lifecycle config/runtime conversion use the same backup, lock/CAS and rollback checks without advancing revisions/causal identities for representation alone. Ordinary inspection and runtime-only mode persistence do not convert files. Upgrade/quiesce all writers before enabling the new code: already-deployed low-level readers cannot be universally fenced by a format number.
359
360
  - Unsupported checkpoint envelopes, combined session metadata, `state.json`, hashed layouts and semantic Pi checkpoint envelopes fail as unsupported, without rewriting existing bytes.
360
361
  - Canonical semantic objects lacking optional fields, such as `intents` or `lazy`, are valid sparse state and do not cross this boundary.
361
- - Before a supported legacy or explicit metadata upgrade is canonically published, the storage owner writes and verifies an exact-byte JSON backup at `<parent-of-store>/<store-name>-migration-backups/<sha256>.json` (created with directory mode 0700, file mode 0600 on the verified platform; existing non-private paths reject). It lists converted scopes and updated paths alongside the transaction's owned file basis, relative paths, identities, Base64 originals and explicit missing entries, including required Session config/runtime. It never discovers unrelated projects/sessions or source bodies. The returned publication exposes `migrationBackup`; completed backups survive rollback and exact retries reuse them. Backup failure blocks canonical writes.
362
- - This backup is recovery evidence outside canonical authority, not a Git commit, journal, automatic fallback or power-loss guarantee. Quiesce writers and request a reviewed complete-cohort recovery before downgrade/restoration; do not overwrite intervening foreign data or restore just one file. Retain backups privately. State Flow 0.x retains legacy conversion and retired-root reservations; the temporary support window ends at State Flow 1.0.0, with unsupported versions still explicitly rejected. Released 0.27.0/0.27.1 retain their converter/reservations, and 0.27.2 preserves that policy; no automatic removal, release or working-store operation follows from consolidation. See the [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names).
362
+ - Before a descriptor upgrade or legacy lifecycle conversion is canonically published, the storage owner writes and verifies an exact-byte JSON backup at `<parent-of-store>/<store-name>-migration-backups/<sha256>.json` (created with directory mode 0700, file mode 0600 on the verified platform; existing non-private paths reject). It lists converted scopes and updated paths alongside the transaction's owned file basis, relative paths, identities, Base64 originals and explicit missing entries, including required Session config/runtime. It never discovers unrelated projects/sessions or source bodies. The returned publication exposes `migrationBackup`; completed backups survive rollback and exact retries reuse them. Backup failure blocks canonical writes.
363
+ - This backup is recovery evidence outside canonical authority, not a Git commit, journal, automatic fallback or power-loss guarantee. Quiesce writers and request a reviewed complete-cohort recovery before downgrade/restoration; do not overwrite intervening foreign data or restore just one file. Retain backups privately. State Flow 1.0.0 removed the temporary `contract`/`working` converter and kept both retired-root names reserved; unsupported versions are still refused explicitly. Need the converter one more time? Use a State Flow 0.x release. See the [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names).
363
364
 
364
365
  ### Conflicts and interrupted publication
365
366
 
package/lib/durable.ts CHANGED
@@ -19,7 +19,7 @@ import {
19
19
  type ArtifactProvenanceRegistry,
20
20
  } from "./artifact.ts";
21
21
  import { MAX_HISTORY_LIMIT } from "./history.ts";
22
- import { prepareSerializedScopeMigration } from "./migration.ts";
22
+ import { prepareSerializedScopeMigration, refuseRetiredSemanticVersion } from "./migration.ts";
23
23
  import { canonicalJson, isJsonValue, isObject, type JsonObject } from "./json.ts";
24
24
  import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
25
25
  import { assertRetainedModules, validateRetainedModules } from "./semantic-module.ts";
@@ -83,7 +83,7 @@ export type ScopeStreamPresence =
83
83
  | { kind: "present"; stream: ScopeStream };
84
84
 
85
85
  function isSupportedScopeMetadataVersion(version: unknown): boolean {
86
- return version === 1 || version === 2 || version === 3 || version === 4;
86
+ return version === 3 || version === 4;
87
87
  }
88
88
 
89
89
  /** Distinguish a wholly absent semantic cohort from partial or malformed surviving authority. */
@@ -110,6 +110,7 @@ export function classifyScopeStream(
110
110
  throw new Error(`Unsupported State Flow ${scope} storage format`);
111
111
  }
112
112
  const metadata = parseMetadataDocument(metaSource, `State Flow ${scope} metadata`);
113
+ if (metadata.version === 1 || metadata.version === 2) refuseRetiredSemanticVersion(metadata.version);
113
114
  if (!isSupportedScopeMetadataVersion(metadata.version)) throw new Error(`Unsupported State Flow ${scope} metadata version`);
114
115
  // In Unicode mode this range matches lone UTF-16 surrogates, not valid pairs or JSON escapes.
115
116
  if ([checkpointSource, patchesSource, metaSource].some((source) => /[\uD800-\uDFFF]/u.test(source))) {
package/lib/extension.ts CHANGED
@@ -2184,6 +2184,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
2184
2184
  });
2185
2185
 
2186
2186
  pi.on("agent_before_settle", async (_event, ctx) => {
2187
+ // Passive has no response reconciliation: its settled run is the accepted turn for already published patches.
2188
+ if (!shuttingDown && snapshot.config.mode === "passive" && memoryToolsAvailable()) backup.markTurnAccepted();
2187
2189
  if (shuttingDown || !memoryToolsAvailable() || !backup.takeSettledTurn()) return;
2188
2190
  const operationSignal = ctx.signal;
2189
2191
  const lifetime = backup.lifetime;
package/lib/healing.ts CHANGED
@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
4
4
  import { constants, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
5
  import { basename, dirname, relative, resolve } from "node:path";
6
6
  import { canonicalJson } from "./json.ts";
7
+ import { RetiredSemanticFormatError } from "./migration.ts";
7
8
  import { sessionRuntimePaths, temporalScopePaths } from "./durable.ts";
8
9
  import { captureScopeSelection, type ScopeSelection } from "./selection.ts";
9
10
  import { RevisionUnavailableError } from "./snapshot.ts";
@@ -40,7 +41,7 @@ export interface HealRequest {
40
41
  */
41
42
  export function isHealableCorruption(error: unknown): boolean {
42
43
  if (!(error instanceof Error)) return false;
43
- if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError) return false;
44
+ if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError || error instanceof RetiredSemanticFormatError) return false;
44
45
  if (error.name === "AbortError") return false;
45
46
  if (typeof (error as NodeJS.ErrnoException).code === "string") return false;
46
47
  if (/identity mismatch/i.test(error.message)) return false;
package/lib/migration.ts CHANGED
@@ -3,14 +3,13 @@ import { resolve } from "node:path";
3
3
  import { parseArtifactProvenanceRegistry } from "./artifact.ts";
4
4
  import { MAX_HISTORY_LIMIT } from "./history.ts";
5
5
  import { canonicalJson, isJsonValue, isObject, validatePatch, type JsonObject, type JsonValue } from "./json.ts";
6
- import { parseStateReadPath, parseValuePath } from "./query.ts";
7
6
  import { assertRetainedModules, validateRetainedModules, type RetainedModules } from "./semantic-module.ts";
8
7
  import { assertNoRetiredSemanticPlanes, type StateScope } from "./state.ts";
9
8
  import { validateScopeStream, type ScopeStream } from "./temporal.ts";
10
9
 
11
- /** Owns temporary pure semantic-dialect conversion; excludes I/O, publication, backup and lifecycle authority. */
10
+ /** Owns the pure v3/v4 semantic codec and module-descriptor upgrade; excludes I/O, publication, backup and lifecycle authority. */
12
11
  export interface SemanticMigrationCandidate {
13
- sourceVersion: 1 | 2 | 3 | 4;
12
+ sourceVersion: 3 | 4;
14
13
  targetVersion: 3 | 4;
15
14
  /** A format conversion is not an authored semantic transition or revision. */
16
15
  requiresConversion: boolean;
@@ -31,57 +30,20 @@ export interface SerializedSemanticMigrationCandidate extends SemanticMigrationC
31
30
  target: Record<ScopeMigrationFile, string>;
32
31
  }
33
32
 
34
- const LEGACY_PLANES = new Map([["contract", "strategy"], ["working", "tactics"]]);
35
- const LEGACY_SEMANTIC_PLANES = new Set(["intents", "contract", "working", "artifacts", "response", "lazy"]);
36
- const LEGACY_LOCATOR = /^(?:((?:effective|global|cwd|session)(?:\[\d+\])?(?:\.patches(?:\[\d+\])?)?)\.)?(contract|working)(?=$|\.|\[)/;
37
- const MARKED_LOCATOR = /(?<![\p{L}\p{N}_$.[\]:/\\-])\$([\p{L}\p{N}_$.[\]:-]+)(?![\p{L}\p{N}_$.[\]:/\\-])/gu;
33
+ /** A known retired format, not corruption: self-healing must never reset it. */
34
+ export class RetiredSemanticFormatError extends Error {}
38
35
 
39
- function translateLocator(path: string): string {
40
- const match = LEGACY_LOCATOR.exec(path);
41
- if (!match) return path;
42
- const [, prefix, plane] = match;
43
- const suffix = path.slice(match[0].length);
44
- try {
45
- if (prefix) parseStateReadPath(prefix, MAX_HISTORY_LIMIT);
46
- // The unchanged lazy root lets the shared parser validate selectors after legacy names retire.
47
- parseValuePath(`lazy${suffix}`);
48
- } catch {
49
- return path;
50
- }
51
- return `${prefix ? `${prefix}.` : ""}${LEGACY_PLANES.get(plane!)!}${suffix}`;
52
- }
53
-
54
- function translateReferences(value: JsonValue): JsonValue {
55
- if (typeof value === "string") return value.replace(MARKED_LOCATOR, (_token, path: string) => `$${translateLocator(path)}`);
56
- if (Array.isArray(value)) return value.map(translateReferences);
57
- if (!isObject(value)) return value;
58
- return Object.fromEntries(Object.entries(value).map(([key, child]) => [key,
59
- key === "$ref" && typeof child === "string" ? translateLocator(child) : translateReferences(child)]));
60
- }
61
-
62
- function translateArtifacts(value: JsonValue): JsonValue {
63
- if (!isObject(value)) return translateReferences(value);
64
- return Object.fromEntries(Object.entries(value).map(([path, card]) => [path, !isObject(card) ? translateReferences(card)
65
- : Object.fromEntries(Object.entries(card).map(([key, child]) => [key,
66
- // Retired embedded provenance is evidence, never a semantic reference namespace.
67
- ["hash", "compiler", "compiled_at"].includes(key) ? structuredClone(child) : translateReferences(child)]))]));
68
- }
69
-
70
- /** Translate a raw legacy checkpoint or replay patch before any known-field filtering. */
71
- export function translateLegacySemanticObject(value: unknown): JsonObject {
72
- validatePatch(value);
73
- for (const plane of LEGACY_PLANES.values()) {
74
- if (Object.hasOwn(value, plane)) throw new Error(`Target State Flow semantic plane in legacy format: ${plane}`);
75
- }
76
- return Object.fromEntries(Object.entries(value).map(([key, child]) => [LEGACY_PLANES.get(key) ?? key,
77
- key === "artifacts" ? translateArtifacts(child) : LEGACY_SEMANTIC_PLANES.has(key) ? translateReferences(child) : structuredClone(child)]));
36
+ /** State Flow 1.0.0 ended the temporary contract/working conversion window; refusal stays explicit. */
37
+ export function refuseRetiredSemanticVersion(version: unknown): never {
38
+ throw new RetiredSemanticFormatError(`Unsupported State Flow semantic metadata version ${String(version)}: legacy contract/working memory is no longer converted since State Flow 1.0.0; open it once with State Flow 0.x to convert it`);
78
39
  }
79
40
 
80
41
  /** Build a detached target candidate; publication still belongs to the guarded storage transaction. */
81
42
  export function prepareSemanticMigration(
82
43
  value: unknown, scope: StateScope, sourceVersion: number, historyLimit = MAX_HISTORY_LIMIT, targetModules?: RetainedModules,
83
44
  ): SemanticMigrationCandidate {
84
- if (sourceVersion !== 1 && sourceVersion !== 2 && sourceVersion !== 3 && sourceVersion !== 4) throw new Error("Unsupported State Flow migration source version");
45
+ if (sourceVersion === 1 || sourceVersion === 2) refuseRetiredSemanticVersion(sourceVersion);
46
+ if (sourceVersion !== 3 && sourceVersion !== 4) throw new Error("Unsupported State Flow migration source version");
85
47
  validatePatch(value);
86
48
  if (!isObject(value.checkpoint) || !Array.isArray(value.patches)) throw new Error("Invalid temporal checkpoint/tail envelope");
87
49
  if (targetModules !== undefined) validateRetainedModules(targetModules);
@@ -93,7 +55,6 @@ export function prepareSemanticMigration(
93
55
  const translate = (state: unknown): JsonObject => {
94
56
  if (sourceVersion !== 4 && targetModules !== undefined && isObject(state)
95
57
  && Object.keys(state).some(key => key.startsWith("x_"))) throw new Error("Legacy State Flow external namespace collision");
96
- if (sourceVersion < 3) return translateLegacySemanticObject(state);
97
58
  validatePatch(state);
98
59
  assertNoRetiredSemanticPlanes(state);
99
60
  return structuredClone(state);
@@ -149,7 +110,8 @@ export function prepareSerializedScopeMigration(
149
110
  const metadata = parseMigrationJson(metaText, "metadata");
150
111
  if (!isObject(metadata)) throw new Error("Invalid State Flow migration metadata");
151
112
  const version = metadata.version;
152
- if (version !== 1 && version !== 2 && version !== 3 && version !== 4) throw new Error("Unsupported State Flow migration source version");
113
+ if (version === 1 || version === 2) refuseRetiredSemanticVersion(version);
114
+ if (version !== 3 && version !== 4) throw new Error("Unsupported State Flow migration source version");
153
115
  if (version === 4) validateRetainedModules(metadata.modules);
154
116
  else if (targetModules !== undefined && Object.hasOwn(metadata, "modules")) throw new Error("Legacy State Flow modules metadata collision");
155
117
  if (scope === "cwd") {
@@ -164,7 +126,7 @@ export function prepareSerializedScopeMigration(
164
126
  if (!isObject(temporal) || !Object.hasOwn(temporal, "checkpoint") || !Array.isArray(temporal.patches)) {
165
127
  throw new Error("Invalid State Flow migration temporal metadata");
166
128
  }
167
- if (version >= 3 && !Object.hasOwn(temporal, "revision")) throw new Error("State Flow target migration metadata requires a revision");
129
+ if (!Object.hasOwn(temporal, "revision")) throw new Error("State Flow target migration metadata requires a revision");
168
130
  const checkpointText = decodeMigrationText(basis.checkpoint.bytes, "checkpoint");
169
131
  const patchesText = decodeMigrationText(basis.patches.bytes, "tail");
170
132
  const checkpoint = parseMigrationJson(checkpointText, "checkpoint");
@@ -174,7 +136,7 @@ export function prepareSerializedScopeMigration(
174
136
  if (boundaries.length !== patches.length) throw new Error("State Flow migration metadata does not match its semantic tail");
175
137
  const candidate = prepareSemanticMigration({
176
138
  ...(version === 4 ? { modules: metadata.modules } : {}),
177
- revision: temporal.revision === undefined ? patches.length : temporal.revision,
139
+ revision: temporal.revision,
178
140
  checkpoint: { through: temporal.checkpoint, state: checkpoint },
179
141
  patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
180
142
  }, scope, version, MAX_HISTORY_LIMIT, targetModules);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.28.0",
3
+ "version": "1.0.0",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",