@llblab/pi-state-flow 0.28.0 → 1.0.1

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,17 @@
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 1.0.1: Documentation Ownership
8
+
9
+ - `Rule owners`: The documentation index now names the single owning page for each rule area, so a rule change lands in one place instead of being restated across contracts. Retired-format guidance elsewhere links to the owning page.
10
+ - `Stale 0.x wording removed`: Index, migration and scope-selection pages no longer claim that `contract`/`working` conversion is still available; they state the 1.0.0 rule that retired cohorts are refused and recovering one needs a State Flow 0.x acceptance first.
11
+
12
+ ## 1.0.0: Automatic Recovery, No Legacy Conversion
13
+
14
+ - `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.
15
+ - `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.
16
+ - `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.
17
+
7
18
  ## 0.28.0: Visible Self-Healing Memory
8
19
 
9
20
  - `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.1",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
package/docs/README.md CHANGED
@@ -16,7 +16,7 @@ Start with the [project README](../README.md) for installation and the memory mo
16
16
  - [Session performance](performance.md): Run synthetic benchmarks, interpret their metrics and understand the current cost model. No provider-cache or latency guarantees.
17
17
  - [Temporal acceptance](temporal-acceptance.md): Find the tests that witness each required property, including cancellation, ownership and replay.
18
18
  - [Semantic handoff contract](semantic-handoff-contract.md): Current Intents / Strategy / Tactics meanings and ownership, the offline-bundle patch corpus and explicitly historical M0 preservation evidence. Deterministic acceptance is not live-model quality evidence.
19
- - [Semantic compatibility decision](semantic-compatibility-decision.md): Shipped semantic migration/support policy, translation oracle, public API impact and historical writer-fence evidence. Core v3 and external-module v4 share Strategy/Tactics; legacy v1/v2 conversion and retired-root reservations remain through State Flow 0.x, with a 1.0.0 cutoff and persistent unsupported-version refusal.
19
+ - [Semantic compatibility decision](semantic-compatibility-decision.md): Shipped semantic migration/support policy, translation oracle, public API impact and historical writer-fence evidence. Core v3 and external-module v4 share Strategy/Tactics; since 1.0.0 retired v1/v2 cohorts are refused with an actionable message and both retired root names stay reserved.
20
20
  - [Scope selection contract](scope-selection-contract.md): Completed [M2 functional boundary](scope-selection-contract.md#m2-functional-acceptance-boundary): seven-selection capture/native runtime, public controls and mode-only optional presentation, with explicit legacy/private proof and operator-inspection limits. Policy data alone grants no memory.
21
21
  - [Single-owner model interface](single-scope-interface-contract.md): Reviewed schema/canonical/native flat tools, protocol/Skills and typed runtime outputs; original-request/foreign-provenance counterexamples, deterministic linked-task/identity checkpoint and actual SDK byte measurements. No live model-quality, token/cache/cost or universal-access claim.
22
22
  - [Public semantic modules](public-module-contract.md): Published `./modules` API since 0.27.0: native-host registration, trusted callbacks, metadata v4 retention, external-root tools, Active/Passive context and atomic Active producers. Owns public integration and currentness boundaries, not dynamic loading or sandboxing.
@@ -25,6 +25,24 @@ Start with the [project README](../README.md) for installation and the memory mo
25
25
  - [Semantic extensibility decision](semantic-extensibility-decision.md): Historical accepted M5 no-new-API decision and atomic-validation countercase. Later explicitly authorized internal/public module work shipped in 0.27.0; no dynamic loader, sandbox, production archive or quality claim follows.
26
26
  - [Semantic memory evaluation](semantic-memory-evaluation.md): Fixed linked-task trial, controlled fixture, independent rubric, isolation/measurement contract and historical credential-safe preflight. Functional implementation has shipped; live-model comparison remains separately authorization-gated and unrun.
27
27
 
28
+ ## Rule owners
29
+
30
+ Each rule has one owning document. Other pages link to it instead of restating it, so a change lands in one place and cannot drift.
31
+
32
+ | Rule | Owner |
33
+ | --- | --- |
34
+ | Modes, configuration, lifecycle commands, storage recovery, self-healing, diagnostics | [usage.md](usage.md) |
35
+ | Per-file recovery rules, durability limit and the transaction rule | [filesystem-recovery.md](filesystem-recovery.md) |
36
+ | Canonical scope format admission, retired versions and required host packages | [compatibility.md](compatibility.md) |
37
+ | Semantic migration history and the settled support policy | [semantic-compatibility-decision.md](semantic-compatibility-decision.md) |
38
+ | Scope selection capture, native policy proof and operator inspection | [scope-selection-contract.md](scope-selection-contract.md) |
39
+ | Temporal lineage, causal identities, storage transactions, Pi lifecycle | [architecture.md](architecture.md) |
40
+ | Fork copy limits | [fork-contract.md](fork-contract.md) |
41
+ | Public module registration and retention | [public-module-contract.md](public-module-contract.md) |
42
+ | Packaged Skill guidance for the model | [../skills](../skills) |
43
+
44
+ Release chronology belongs to [CHANGELOG.md](../CHANGELOG.md), never to a rule statement.
45
+
28
46
  ## Development policy
29
47
 
30
48
  - [Agent contract relocation ledger](agent-contract-relocation.md): Audit map from [AGENTS.md](../AGENTS.md) development instructions to their owning contracts and tests. It is provenance evidence, not a user guide or an open-work list.
@@ -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
 
@@ -738,7 +738,7 @@ The native seven-selection bridge, public scope controls and mode-only optional
738
738
  - **Lifecycle v1:** It has no accepted excluded-owner witness skeleton. Safe admission requires the complete three-owner semantic/provenance cohort plus config/runtime (the full 11-file proof) before projection. An excluded body's corruption can therefore reject v1 admission. Only owned acceptance with verified exact-byte backup can upgrade; excluded owners remain byte-identical. No selective parser pretends this legacy dependency disappeared.
739
739
  - **Lifecycle v2:** Only selected semantic bodies/provenance plus config/runtime are opened for ordinary selected admission. Acquired excluded Session still requires regular-file/path-chain presence of its private triple, not body reads; unacquired/deferred targets require absence. Retained private causal proof stays lifecycle metadata and cannot be invented by mode changes, observation or missing files.
740
740
  - **Explicit operator inspection:** Current Telegram buttons/help follow wanted participation, not sparse availability. Effective is offered only for2+ owners and reads only that selected overlay; selected shared-only inspection does not require excluded Session bodies. Session/current proof still fails closed, and lifecycle-v1 admission retains its complete-cohort dependency. Disposable Off reads publish/install nothing, clear no fence and grant no private acquisition. This is not automatic Off memory access or a confidentiality promise.
741
- - **Unsupported/foreign evidence:** Unknown epochs, malformed identity/selection/causal proof, old low-level writers without the supported fence and working-store migration are not repaired by this checkpoint. The [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names) retains legacy conversion/root reservations throughout State Flow0.x and ends that temporary window beginning1.0.0, with unsupported-version refusal retained. Released 0.27.0/0.27.1 and this consolidation retain the converter and retired-root reservations; no transition plan, release or working-store operation is implied.
741
+ - **Unsupported/foreign evidence:** Unknown epochs, malformed identity/selection/causal proof, old low-level writers without the supported fence and working-store migration are not repaired by this checkpoint. The [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names) owns the current rule: retired roots stay reserved, v1/v2 cohorts are refused since 1.0.0, and recovering one needs a State Flow 0.x acceptance first.
742
742
 
743
743
  ### Current scope-aware presentation
744
744
 
@@ -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
 
@@ -160,7 +158,7 @@ Native `classifyScopeStream` (and therefore `parseScopeStream`/`loadScopeStream`
160
158
  - Do not insert invalid old-plane sentinel values, materialized nulls, duplicated semantic aliases, or new hidden memory just to trip an older validator.
161
159
  - An owner-format fence must survive unknown metadata siblings, sparse state, absent provenance registries, and the first target write. Off, inspection and runtime-only mode persistence cannot convert. An accepted owned Start transaction can; a UI receipt or pure policy choice alone grants no publication authority.
162
160
 
163
- **Supported boundary:** Upgrade/quiesce all cooperating writers; unsafe low-level mixed-version clients are not supported. If a deployment requires coexistence with one, do not convert that store without a separately reviewed bridge/representation. Broad implementation authorization does not authorize exact-store rollout. Legacy conversion and retired-root reservations remain supported throughout State Flow 0.x; their temporary support window ends at State Flow 1.0.0, while explicit unsupported-version refusal remains. Released 0.27.0/0.27.1 retain their converter/reservations; no removal or working-store conversion is authorized by this consolidation.
161
+ **Supported boundary:** Upgrade/quiesce all cooperating writers; unsafe low-level mixed-version clients are not supported. If a deployment requires coexistence with one, do not convert that store without a separately reviewed bridge/representation. Broad implementation authorization does not authorize exact-store rollout. Retired-root reservations and explicit unsupported-version refusal remain; recovering a v1/v2 store needs one State Flow 0.x acceptance first (see the [settled support policy](#implementation-direction-and-reserved-names)).
164
162
 
165
163
  ## Public API impact inventory
166
164
 
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.1",
4
4
  "license": "MIT",
5
5
  "private": false,
6
6
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",