@llblab/pi-state-flow 0.17.4 → 0.18.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/lib/temporal.ts CHANGED
@@ -21,6 +21,8 @@ export interface TemporalPatch {
21
21
  }
22
22
 
23
23
  export interface ScopeStream {
24
+ /** Monotonic semantic revision owned by this scope; independent of branch-local boundary positions. */
25
+ revision: number;
24
26
  checkpoint: ScopeCheckpoint;
25
27
  patches: TemporalPatch[];
26
28
  }
@@ -32,6 +34,7 @@ export interface TemporalState {
32
34
  }
33
35
 
34
36
  const SCOPES: StateScope[] = ["global", "cwd", "session"];
37
+ export type ScopeRevisions = Record<StateScope, number>;
35
38
 
36
39
  function validateHistoryLimit(limit: number): void {
37
40
  if (!Number.isSafeInteger(limit) || limit < 0 || limit > MAX_HISTORY_LIMIT) {
@@ -69,7 +72,8 @@ function sameBoundary(left: TransitionBoundary, right: TransitionBoundary): bool
69
72
  export function validateScopeStream(value: unknown, scope: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): asserts value is ScopeStream {
70
73
  validateHistoryLimit(historyLimit);
71
74
  if (!SCOPES.includes(scope)) throw new Error("Unknown temporal scope");
72
- if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches"
75
+ if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches,revision"
76
+ || !Number.isSafeInteger(value.revision) || (value.revision as number) < 0
73
77
  || !isObject(value.checkpoint) || Object.keys(value.checkpoint).sort().join(",") !== "state,through"
74
78
  || !Array.isArray(value.patches)) {
75
79
  throw new Error("Invalid temporal checkpoint/tail envelope");
@@ -78,6 +82,7 @@ export function validateScopeStream(value: unknown, scope: StateScope, historyLi
78
82
  validateBoundary(stream.checkpoint.through);
79
83
  validateState(stream.checkpoint.state);
80
84
  if (stream.patches.length > historyLimit) throw new Error(`Temporal scope tail exceeds configured history limit ${historyLimit}`);
85
+ if (stream.revision < stream.patches.length) throw new Error("Temporal scope revision predates its retained patch tail");
81
86
  let previous = stream.checkpoint.through;
82
87
  let state = stream.checkpoint.state;
83
88
  const identities = new Set([previous.id]);
@@ -191,6 +196,7 @@ export function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id
191
196
  export function createTemporalState(states: ScopedStates, id: string, historyLimit = DEFAULT_HISTORY_LIMIT): TemporalState {
192
197
  const through: TransitionBoundary = { id, position: 0, parent: null };
193
198
  const stream = (scope: StateScope): ScopeStream => ({
199
+ revision: 0,
194
200
  checkpoint: { through: structuredClone(through), state: structuredClone(states[scope]) },
195
201
  patches: [],
196
202
  });
@@ -234,7 +240,9 @@ export function selectScopeStreamAtBoundary(stream: ScopeStream, scope: StateSco
234
240
  throw new Error("Selected State Flow history boundary predates the retained scope checkpoint");
235
241
  }
236
242
  const selected = structuredClone(stream);
237
- selected.patches = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
243
+ const retained = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
244
+ selected.revision -= selected.patches.length - retained.length;
245
+ selected.patches = retained;
238
246
  validateScopeStream(selected, scope, historyLimit);
239
247
  return selected;
240
248
  }
@@ -250,12 +258,28 @@ export function selectTemporalStateBoundary(view: TemporalState, boundaryId: str
250
258
  const selected = structuredClone(view);
251
259
  selected.lineage = selected.lineage.slice(0, index + 1);
252
260
  for (const scope of SCOPES) {
253
- selected.scopes[scope].patches = selected.scopes[scope].patches.filter(({ transition }) => transition.position <= target.position);
261
+ const stream = selected.scopes[scope];
262
+ const retained = stream.patches.filter(({ transition }) => transition.position <= target.position);
263
+ stream.revision -= stream.patches.length - retained.length;
264
+ stream.patches = retained;
254
265
  }
255
266
  validateTemporalState(selected, historyLimit);
256
267
  return selected;
257
268
  }
258
269
 
270
+ /** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
271
+ export function temporalScopeRevisions(view: TemporalState): ScopeRevisions {
272
+ const revisions = {
273
+ global: view.scopes.global.revision,
274
+ cwd: view.scopes.cwd.revision,
275
+ session: view.scopes.session.revision,
276
+ };
277
+ if (Object.values(revisions).some((revision) => !Number.isSafeInteger(revision) || revision < 0)) {
278
+ throw new Error("Invalid State Flow scope revision vector");
279
+ }
280
+ return revisions;
281
+ }
282
+
259
283
  /** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
260
284
  export function readTemporalState(view: TemporalState, offset = 0, scope?: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): MaterializedState {
261
285
  validateHistoryLimit(historyLimit);
@@ -298,6 +322,8 @@ export function advanceTemporalState(
298
322
  const next = structuredClone(view);
299
323
  for (const { scope, patch } of changes) {
300
324
  const stream = next.scopes[scope];
325
+ if (stream.revision >= Number.MAX_SAFE_INTEGER) throw new Error(`State Flow ${scope} scope revision is exhausted`);
326
+ stream.revision += 1;
301
327
  if (historyLimit === 0) {
302
328
  stream.checkpoint = { through: structuredClone(boundary), state: apply(scopeAt(stream, head), patch) };
303
329
  stream.patches = [];
package/lib/transition.ts CHANGED
@@ -257,8 +257,8 @@ export function stageScopedTransition(
257
257
  causalBasis: string,
258
258
  successfulArtifactReads: Iterable<SuccessfulArtifactRead> = [],
259
259
  ): StagedScopedTransition {
260
- if (typeof transition.response !== "string" || transition.response.trim().length === 0) {
261
- throw new Error("Accepted State Flow response body must be non-empty");
260
+ if (typeof transition.response !== "string") {
261
+ throw new Error("Accepted State Flow response body must be a string");
262
262
  }
263
263
  return stageScopedSemanticTransition(
264
264
  currentStates,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llblab/pi-state-flow",
3
- "version": "0.17.4",
3
+ "version": "0.18.1",
4
4
  "private": false,
5
5
  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
6
6
  "keywords": [