@llblab/pi-state-flow 0.24.0 → 0.25.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 +1 -1
- package/BACKLOG.md +15 -12
- package/CHANGELOG.md +14 -0
- package/README.md +116 -34
- package/dist/lib/acquisition.d.ts +24 -1
- package/dist/lib/acquisition.js +80 -1
- package/dist/lib/compaction.d.ts +17 -0
- package/dist/lib/compaction.js +40 -0
- package/dist/lib/context.d.ts +4 -2
- package/dist/lib/context.js +7 -2
- package/dist/lib/extension.js +149 -298
- package/dist/lib/git.d.ts +29 -0
- package/dist/lib/git.js +58 -0
- package/dist/lib/operation.d.ts +37 -0
- package/dist/lib/operation.js +59 -0
- package/dist/lib/ownership.d.ts +31 -0
- package/dist/lib/ownership.js +117 -0
- package/dist/lib/protocol.d.ts +1 -1
- package/dist/lib/protocol.js +8 -8
- package/dist/lib/query.js +1 -1
- package/dist/lib/status.d.ts +2 -0
- package/dist/lib/status.js +28 -0
- package/dist/lib/transition.d.ts +3 -0
- package/dist/lib/transition.js +8 -1
- package/dist/package.json +1 -1
- package/dist/skills/state-flow-guide/SKILL.md +15 -7
- package/dist/skills/state-flow-memory/SKILL.md +2 -2
- package/docs/README.md +19 -9
- package/docs/agent-contract-relocation.md +4 -4
- package/docs/architecture.md +645 -91
- package/docs/compatibility.md +116 -37
- package/docs/filesystem-recovery.md +118 -21
- package/docs/fork-contract.md +68 -8
- package/docs/lazy-state.md +90 -14
- package/docs/performance.md +83 -66
- package/docs/temporal-acceptance.md +391 -62
- package/docs/usage.md +317 -62
- package/lib/acquisition.ts +85 -1
- package/lib/compaction.ts +47 -0
- package/lib/context.ts +9 -2
- package/lib/extension.ts +161 -295
- package/lib/git.ts +63 -0
- package/lib/operation.ts +75 -0
- package/lib/ownership.ts +120 -0
- package/lib/protocol.ts +8 -9
- package/lib/query.ts +1 -1
- package/lib/runtime.ts +1 -1
- package/lib/snapshot.ts +1 -2
- package/lib/status.ts +29 -0
- package/lib/transition.ts +9 -1
- package/package.json +1 -1
- package/skills/state-flow-guide/SKILL.md +15 -7
- package/skills/state-flow-memory/SKILL.md +2 -2
package/docs/README.md
CHANGED
|
@@ -1,11 +1,21 @@
|
|
|
1
1
|
# State Flow documentation
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- [
|
|
8
|
-
- [
|
|
9
|
-
- [
|
|
10
|
-
- [
|
|
11
|
-
|
|
3
|
+
Start with the [project README](../README.md) for installation and the memory model.
|
|
4
|
+
|
|
5
|
+
## Operating State Flow
|
|
6
|
+
|
|
7
|
+
- [Usage and recovery](usage.md): Configure State Flow, choose Active/Passive/Off, inspect memory and recover from storage problems. Includes diagnostics and privacy rules.
|
|
8
|
+
- [Lazy state](lazy-state.md): Store ordinary JSON in `lazy` outside baseline context, read it progressively with structural `meta` + `keys`, patch array indices and understand intent ownership.
|
|
9
|
+
- [Filesystem recovery](filesystem-recovery.md): What to do when files are missing, incomplete or malformed; which evidence authorizes repair and what durability is promised.
|
|
10
|
+
- [Physical fork contract](fork-contract.md): What a child session copies, what stays live, how cancellation works and which forks are supported.
|
|
11
|
+
|
|
12
|
+
## Integration and verification
|
|
13
|
+
|
|
14
|
+
- [Architecture](architecture.md): Semantic state, temporal history, Pi lifecycle, storage transactions, artifact acquisition and embedding APIs.
|
|
15
|
+
- [SDK compatibility](compatibility.md): Required packages, verified environments, host lifecycle requirements and isolated validation procedures.
|
|
16
|
+
- [Session performance](performance.md): Run synthetic benchmarks, interpret their metrics and understand the current cost model. No provider-cache or latency guarantees.
|
|
17
|
+
- [Temporal acceptance](temporal-acceptance.md): Find the tests that witness each required property, including cancellation, ownership and replay.
|
|
18
|
+
|
|
19
|
+
## Development policy
|
|
20
|
+
|
|
21
|
+
- [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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent contract relocation ledger
|
|
2
2
|
|
|
3
|
-
This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pre-compaction `AGENTS.md` (SHA-256 `0d328eacc96d6b67c5eb036a51adc27e1dcd24d20bb6695f2fff6d5a3c87737b`; source lines 3–58, based on commit `70baecde` plus the Passive-footprint and `barrier-block` edits). Each `L##` identifies exactly one original bullet/paragraph. Its destination is the current owner of that paragraph's reusable contract; where necessary, a compact root rule or executable witness is also named. The root remains approximately 1,300 words; its
|
|
3
|
+
This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pre-compaction `AGENTS.md` (SHA-256 `0d328eacc96d6b67c5eb036a51adc27e1dcd24d20bb6695f2fff6d5a3c87737b`; source lines 3–58, based on commit `70baecde` plus the Passive-footprint and `barrier-block` edits). Each `L##` identifies exactly one original bullet/paragraph. Its destination is the current owner of that paragraph's reusable contract; where necessary, a compact root rule or executable witness is also named. The root remains approximately 1,300 words; its current default-mode rule (new sessions start Off) supersedes the source's Passive-default clause. This is a reviewed documentation trace, not a claim that prose links alone prove runtime correctness.
|
|
4
4
|
|
|
5
5
|
## Composition, semantics, and model access
|
|
6
6
|
|
|
@@ -35,7 +35,7 @@ This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pr
|
|
|
35
35
|
- L19 canonical layout and identity → [storage and identity](architecture.md#storage-and-identity).
|
|
36
36
|
- L20 optimistic durability, optional backup and contention → [power-loss boundary](filesystem-recovery.md#power-loss-durability), [asynchronous transaction](architecture.md#asynchronous-storage-transaction), [optional Git backup](architecture.md#optional-git-backup).
|
|
37
37
|
- L21 cohort classification and missing shared pairs → [recovery](usage.md#missing-partial-and-malformed-storage), [transaction rule](filesystem-recovery.md#transaction-rule).
|
|
38
|
-
- L22 predecessor formats and no in-place migration → [format boundary](usage.md#moving-a-store-and-
|
|
38
|
+
- L22 predecessor formats and no in-place migration → [format boundary](usage.md#moving-a-store-and-supported-formats), [optional Git backup](architecture.md#optional-git-backup).
|
|
39
39
|
- L23 exact-file CAS, awaited transaction and rollback → [asynchronous transaction](architecture.md#asynchronous-storage-transaction), [storage and identity](architecture.md#storage-and-identity), [transaction rule](filesystem-recovery.md#transaction-rule).
|
|
40
40
|
- L24 initialization and exact-source fork → [Pi lifecycle](architecture.md#pi-lifecycle), [fork contract](fork-contract.md).
|
|
41
41
|
- L25 retained-boundary restore, failed-Stop read-only recovery and selection races → [Pi lifecycle](architecture.md#pi-lifecycle), [mode restoration](compatibility.md#mode-selection-and-memory-restoration).
|
|
@@ -51,7 +51,7 @@ This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pr
|
|
|
51
51
|
## Operator, agent, and development policy
|
|
52
52
|
|
|
53
53
|
- L30 terminal handoff plane routing → [operational guidance](architecture.md#operational-guidance-and-memory-curation), [semantic state](architecture.md#semantic-state).
|
|
54
|
-
- L31 consequential evidence, semantic references and dangling hints → [model tools](architecture.md#model-tools), [lazy navigation](usage.md#lazy-navigation-and-historical-reading), [memory curation](architecture.md#operational-guidance-and-memory-curation).
|
|
54
|
+
- L31 consequential evidence, semantic references and dangling hints → [model tools](architecture.md#model-tools), [lazy navigation](usage.md#lazy-navigation-and-historical-reading), [memory curation](architecture.md#operational-guidance-and-memory-curation). The root's intent-ownership exception to reference semantics is owned by [intent ownership](lazy-state.md#intent-ownership).
|
|
55
55
|
- L32 volatile observation and external-effects revalidation → [operational boundaries](../README.md#operational-boundaries), [memory guidance](usage.md#memory-and-source-acquisition).
|
|
56
56
|
- L33 registered Skill acquisition → [artifact routing](architecture.md#artifact-routing).
|
|
57
57
|
- L34 bounded curation and verified transfers → [operational guidance](architecture.md#operational-guidance-and-memory-curation), [memory Skill](../skills/state-flow-memory/SKILL.md).
|
|
@@ -69,4 +69,4 @@ This is the source-bound **paragraph-to-owner parity map** for the 8,141-word pr
|
|
|
69
69
|
|
|
70
70
|
## Verification evidence
|
|
71
71
|
|
|
72
|
-
The map names all 56 source paragraphs exactly once. Each was compared with its destinations; the highest-risk clause groups were checked explicitly: L06/L45 native run anchors and Stop context, L23–L26 CAS/backup/rollback, L28 receipt-elision bounds, L31 reference/epistemic limits, L36 diagnostic privacy, L47 native compaction and L50 callback revocation. An additional exact-code-token audit exposed otherwise easy-to-lose clauses: legacy `{disabled:true}`, in-memory header key derivation, materialization equality, `contract.compiled_skills` rejection, Skill compiler revision, runtime-origin null exception and normalized artifact replay. Those are now stated in architecture; terse `patches[n]` and `{value:null, hint:[...]}` from the source are represented there by the more precise scoped patch path and expanded dangling-reference sentinel. The remaining uniquely durable developer rules, including no live-store fixture edits, stay in the compact root.
|
|
72
|
+
The map names all 56 source paragraphs exactly once. Each was compared with its destinations; the highest-risk clause groups were checked explicitly: L06/L45 native run anchors and Stop context, L23–L26 CAS/backup/rollback, L28 receipt-elision bounds, L31 reference/epistemic limits, L36 diagnostic privacy, L47 native compaction and L50 callback revocation. An additional exact-code-token audit exposed otherwise easy-to-lose clauses: legacy `{disabled:true}`, in-memory header key derivation, materialization equality, `contract.compiled_skills` rejection, Skill compiler revision, runtime-origin null exception and normalized artifact replay. Those are now stated in architecture; terse `patches[n]` and `{value:null, hint:[...]}` from the source are represented there by the more precise scoped patch path and expanded dangling-reference sentinel. The remaining uniquely durable developer rules, including no live-store fixture edits, stay in the compact root. The relocation itself changed no tests; native and domain-specific witnesses remain in their named test files. Later structural guards in `tests/invariants.test.ts` enforce composition-root ownership and do not alter this mapping. Package, context and domain-DAG validation establish the final checked boundary; they cannot substitute for semantic judgment about future models.
|