@llblab/pi-state-flow 0.4.0 → 0.5.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/lib/extension.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { execFile } from "node:child_process";
1
2
  import type { AgentMessage } from "@earendil-works/pi-agent-core";
2
3
  import { StringEnum, Type } from "@earendil-works/pi-ai";
3
4
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -16,14 +17,20 @@ import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTR
16
17
  import { compactStatus, detailedStatus, STATUS_KEY, type PendingPublicationDiagnostic, type StatusDiagnostics } from "./status.ts";
17
18
  import { abandonValidation, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
18
19
  import { recoverSnapshot } from "./recovery.ts";
20
+ import type { RehydrationPhase } from "./rehydration.ts";
21
+ import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.ts";
22
+ import { coalescePublicationTarget, createPublicationQueue, type PublicationQueueState } from "./publication.ts";
23
+ import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.ts";
24
+ import { runPublicationWorker } from "./publication.ts";
19
25
  import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
20
26
  import {
21
27
  cwdScopeKey,
28
+ resolveSessionAddress,
22
29
  sessionScopeKey,
23
- sessionStorageKey,
30
+ type SessionAddress,
24
31
  } from "./durable.ts";
25
32
  import { projectRecentTransitionsWithLimit } from "./history.ts";
26
- import { pushGitCommit } from "./git.ts";
33
+ import { isGitCommitAncestor, pushGitCommit, resolveGitPushDestination } from "./git.ts";
27
34
  import {
28
35
  ORDINARY_ARTIFACT_COMPILER,
29
36
  planArtifactInvalidation,
@@ -52,15 +59,21 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
52
59
  let runtime: TemporalRuntime | undefined;
53
60
  let activeContext: ExtensionContext | undefined;
54
61
  let pendingPublication: PendingPublicationDiagnostic | undefined;
62
+ let rehydrationPhase: RehydrationPhase | undefined;
63
+ let turnPublicationTarget: string | undefined;
64
+ const activePublicationWorkers = new Set<string>();
55
65
  const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
56
66
  const skillReads = new SkillReadTracker();
57
67
  const artifactReads = new ArtifactReadTracker();
58
68
  const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(options.agentDir));
59
69
  let artifactInvalidations: ArtifactInvalidationRequest[] = [];
60
70
 
61
- function sessionIdentity(ctx: ExtensionContext): { id: string; key: string } {
62
- const id = ctx.sessionManager.getSessionId();
63
- return { id, key: sessionStorageKey(ctx.sessionManager.getSessionFile(), id, ctx.sessionManager.getHeader()?.timestamp) };
71
+ function sessionAddress(ctx: ExtensionContext): SessionAddress {
72
+ return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
73
+ }
74
+
75
+ function createRuntime(ctx: ExtensionContext): TemporalRuntime {
76
+ return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot);
64
77
  }
65
78
 
66
79
  options.onRuntime?.({ read: (offset, scope) => {
@@ -69,7 +82,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
69
82
  } });
70
83
 
71
84
  function persist(): void {
72
- const publication = runtime?.view ? runtime.publish(snapshot) : undefined;
85
+ const mode = snapshot.meta.remotePublication?.mode ?? "transition";
86
+ const publication = runtime?.view ? runtime.publish(snapshot, false, undefined, { pushRemote: mode === "transition" }) : undefined;
87
+ if (publication?.commit && mode === "turn-end") turnPublicationTarget = publication.commit;
73
88
  if (publication && activeContext) recordPublication(publication, activeContext);
74
89
  const checkpoint = persistableSnapshot(snapshot);
75
90
  if ("disabled" in checkpoint && !branchStartsWithoutRuntime) {
@@ -182,7 +197,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
182
197
  const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
183
198
  const committed = commitScopedTransition(snapshot, scopeStates, stage, (accepted, nextSnapshot) => {
184
199
  if (!runtime?.view) throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
185
- const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted);
200
+ const mode = nextSnapshot.meta.remotePublication?.mode ?? "transition";
201
+ const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, { pushRemote: mode === "transition" });
202
+ if (publication?.commit && mode === "turn-end") turnPublicationTarget = publication.commit;
186
203
  if (publication) recordPublication(publication, ctx);
187
204
  }, runtime!.causalBasis(), { finalizeRun });
188
205
  if (!committed) return false;
@@ -195,6 +212,70 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
195
212
  return true;
196
213
  }
197
214
 
215
+ function enqueueTurnPublication(): void {
216
+ const target = turnPublicationTarget;
217
+ turnPublicationTarget = undefined;
218
+ if (!target) return;
219
+ const destination = resolveGitPushDestination(repositoryRoot);
220
+ if (!destination) return;
221
+ const path = publicationQueuePath(destination);
222
+ const previous = loadPublicationQueue(path);
223
+ const next = previous
224
+ ? coalescePublicationTarget(previous, destination, target, (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant))
225
+ : createPublicationQueue(destination, target);
226
+ savePublicationQueue(path, next, previous);
227
+ }
228
+
229
+ function launchPublicationWorker(): void {
230
+ let destination: ReturnType<typeof resolveGitPushDestination>;
231
+ try {
232
+ destination = resolveGitPushDestination(repositoryRoot);
233
+ } catch (error) {
234
+ if (error instanceof Error && /ENOENT/.test(error.message)) return;
235
+ throw error;
236
+ }
237
+ if (!destination) return;
238
+ const path = publicationQueuePath(destination);
239
+ if (activePublicationWorkers.has(path)) return;
240
+ let queued: PublicationQueueState | undefined;
241
+ let lease: ReturnType<typeof acquirePublicationWorkerLease>;
242
+ try {
243
+ queued = loadPublicationQueue(path);
244
+ if (!queued) return;
245
+ lease = acquirePublicationWorkerLease(path);
246
+ } catch {
247
+ return;
248
+ }
249
+ if (!lease) return;
250
+ activePublicationWorkers.add(path);
251
+ void runPublicationWorker(
252
+ queued,
253
+ ({ target }) => new Promise<void>((resolve, reject) => {
254
+ execFile("git", ["-C", repositoryRoot, "push", destination.remote, `${target}:${destination.ref}`], {
255
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
256
+ }, (error) => error ? reject(error) : resolve());
257
+ }),
258
+ () => loadPublicationQueue(path) ?? queued,
259
+ (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant),
260
+ ).then((result) => {
261
+ const current = loadPublicationQueue(path);
262
+ if (!current) return;
263
+ if (result.next === undefined) {
264
+ if (current.target === result.attempted.target) removePublicationQueue(path, current);
265
+ return;
266
+ }
267
+ if (current.target === result.attempted.target || result.next.target === current.target) {
268
+ savePublicationQueue(path, result.next, current);
269
+ }
270
+ }).catch(() => {
271
+ // Queue/CAS truth remains durable; status and a later activation expose retry.
272
+ }).finally(() => {
273
+ activePublicationWorkers.delete(path);
274
+ lease.release();
275
+ if (loadPublicationQueue(path)?.status === "pending") launchPublicationWorker();
276
+ });
277
+ }
278
+
198
279
  function retryPendingPush(ctx: ExtensionContext): void {
199
280
  if (pendingPublication === undefined || !runtime?.view) return;
200
281
  const result = pushGitCommit(repositoryRoot, pendingPublication.commit);
@@ -210,6 +291,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
210
291
  }
211
292
  }
212
293
 
294
+ function currentRehydrationPhase(): RehydrationPhase | undefined {
295
+ return rehydrationPhase;
296
+ }
297
+
213
298
  function statusDiagnostics(ctx: ExtensionContext): StatusDiagnostics {
214
299
  const cwd = ctx.cwd;
215
300
  const diagnosticStates = scopeStates;
@@ -239,7 +324,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
239
324
  }
240
325
  }
241
326
 
242
- const session = sessionIdentity(ctx);
327
+ const session = sessionAddress(ctx);
328
+ let publicationQueue: PublicationQueueState | undefined;
329
+ let publicationQueueError: string | undefined;
330
+ try {
331
+ const destination = resolveGitPushDestination(repositoryRoot);
332
+ publicationQueue = destination ? loadPublicationQueue(publicationQueuePath(destination)) : undefined;
333
+ } catch (error) {
334
+ publicationQueue = undefined;
335
+ publicationQueueError = error instanceof Error ? error.message : String(error);
336
+ }
243
337
  return {
244
338
  repositoryRoot,
245
339
  cwdScopeKey: cwdScopeKey(cwd),
@@ -256,14 +350,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
256
350
  ...(durableStateError === undefined ? {} : { durableStateError }),
257
351
  ...(pendingPublication === undefined ? {} : { pendingPublication }),
258
352
  retryQueued,
353
+ ...(publicationQueue === undefined ? {} : { publicationQueue }),
354
+ ...(publicationQueueError === undefined ? {} : { publicationQueueError }),
259
355
  };
260
356
  }
261
357
 
262
358
  function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown): void {
263
359
  clearRunTransient();
264
360
  activeContext = ctx;
265
- const session = sessionIdentity(ctx);
266
- runtime = new TemporalRuntime(ctx.cwd, session.id, repositoryRoot, session.key);
361
+ const session = sessionAddress(ctx);
362
+ runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot);
267
363
  installScopeStates();
268
364
  pendingPublication = undefined;
269
365
  branchHasSnapshot = false;
@@ -293,6 +389,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
293
389
  installScopeStates();
294
390
  } else if (config.autoStart && isNewSession(sessionStartReason, branch)) {
295
391
  snapshot = startEpisode(hasPriorConversation(branch));
392
+ snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(
393
+ resolveRemotePublicationPolicy(config.remotePublication, { legacyRuntime: false }),
394
+ );
296
395
  runtime.prepare();
297
396
  const initialization = runtime.initialize(snapshot, true);
298
397
  if (initialization) recordPublication(initialization, ctx);
@@ -317,6 +416,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
317
416
  meta: { ...snapshot.meta, validation: failure.meta.validation },
318
417
  };
319
418
  }
419
+ if (branchHasSnapshot && snapshot.meta.remotePublication === undefined) {
420
+ snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(
421
+ resolveRemotePublicationPolicy(undefined, { legacyRuntime: true }),
422
+ );
423
+ }
424
+ if (snapshot.config.enabled && snapshot.meta.remotePublication === undefined) {
425
+ snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(
426
+ resolveRemotePublicationPolicy(undefined, { legacyRuntime: true }),
427
+ );
428
+ }
320
429
  pendingPublication = snapshot.meta.pendingPublication === undefined
321
430
  ? undefined
322
431
  : structuredClone(snapshot.meta.pendingPublication);
@@ -406,9 +515,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
406
515
  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
407
516
  if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
408
517
  if (signal?.aborted) throw new Error("State Flow patch was aborted before materialization");
518
+ const transition = { scope: params.scope as StateScope, patch: params.patch as ScopePatch };
409
519
  const stage = stageScopedPatch(
410
520
  scopeStates,
411
- { scope: params.scope as StateScope, patch: params.patch as ScopePatch },
521
+ transition,
412
522
  skillReads.successful.values(),
413
523
  runtime!.causalBasis(),
414
524
  artifactReads.successful.values(),
@@ -417,7 +527,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
417
527
  updateUi(ctx);
418
528
  const publication = pendingPublication === undefined ? "" : "; durable publication pending";
419
529
  return {
420
- content: [{ type: "text", text: `State materialized at ${params.scope} scope${publication}.` }],
530
+ content: [{ type: "text", text: `\nState materialized at ${params.scope} scope${publication}.` }],
421
531
  details: { scope: params.scope, step: snapshot.meta.step },
422
532
  };
423
533
  },
@@ -434,8 +544,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
434
544
  }
435
545
  const branch = ctx.sessionManager.getBranch();
436
546
  activeContext = ctx;
437
- const session = sessionIdentity(ctx);
438
- runtime ??= new TemporalRuntime(ctx.cwd, session.id, repositoryRoot, session.key);
547
+ runtime ??= createRuntime(ctx);
439
548
  if (branchStartsWithoutRuntime) runtime.prepare();
440
549
  const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
441
550
  && hasPriorConversation(branch);
@@ -444,9 +553,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
444
553
  setPendingPublication(snapshot.meta.pendingPublication);
445
554
  branchHasSnapshot = true;
446
555
  }
447
- snapshot = branchHasSnapshot
556
+ const existingBranch = branchHasSnapshot;
557
+ snapshot = existingBranch
448
558
  ? resumeEpisode(snapshot, bootstrap)
449
559
  : startEpisode(bootstrap);
560
+ if (snapshot.meta.remotePublication === undefined) {
561
+ snapshot.meta.remotePublication = serializeRemotePublicationPolicyDocument(
562
+ resolveRemotePublicationPolicy(existingBranch ? undefined : config.remotePublication, { legacyRuntime: existingBranch }),
563
+ );
564
+ }
450
565
  branchHasSnapshot = true;
451
566
  const publication = runtime.view
452
567
  ? runtime.promote(snapshot) ?? runtime.publish(snapshot)
@@ -490,8 +605,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
490
605
  let selected = runtime;
491
606
  let current = snapshot;
492
607
  if (!selected?.view && snapshot.meta.durableBase) {
493
- const session = sessionIdentity(ctx);
494
- selected = new TemporalRuntime(ctx.cwd, session.id, repositoryRoot, session.key);
608
+ selected = createRuntime(ctx);
495
609
  current = selected.restore(snapshot.meta.durableBase, snapshot);
496
610
  }
497
611
  const stopped = stopEpisode(current);
@@ -517,6 +631,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
517
631
  artifactReads.clear();
518
632
  }
519
633
  const rotatesRun = snapshot.meta.specification !== undefined && !retryQueued;
634
+ if (rotatesRun) rehydrationPhase = "step";
520
635
  if (prepareRun(snapshot, event.prompt, retryQueued)) {
521
636
  if (rotatesRun) runAnchorTimestamp = undefined;
522
637
  persist();
@@ -533,9 +648,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
533
648
  snapshot.config.transitionWindow,
534
649
  runtime?.recent() ?? [],
535
650
  );
651
+ const activeRehydrationPhase = currentRehydrationPhase();
536
652
  if (snapshot.meta.bootstrap) {
537
653
  const messages = withoutPrivateValidation(event.messages as AgentMessage[]);
538
- return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, artifactInvalidations), ...messages] };
654
+ return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, artifactInvalidations, activeRehydrationPhase), ...messages] };
539
655
  }
540
656
  const trajectory = currentRunTrajectory(
541
657
  event.messages as AgentMessage[],
@@ -545,7 +661,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
545
661
  runAnchorTimestamp = trajectory.anchorTimestamp;
546
662
  return {
547
663
  messages: [
548
- runtimeContextMessage(snapshot, effectiveState, recentTransitions, artifactInvalidations),
664
+ runtimeContextMessage(snapshot, effectiveState, recentTransitions, artifactInvalidations, activeRehydrationPhase),
549
665
  ...trajectory.messages,
550
666
  ],
551
667
  };
@@ -629,6 +745,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
629
745
  try {
630
746
  stagedFinal.nextStates.session.response = finalizedAssistantResponse(event.message);
631
747
  commitStage(stagedFinal, ctx, true);
748
+ enqueueTurnPublication();
749
+ if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
632
750
  } catch (error) {
633
751
  queueTerminalRegeneration(error instanceof Error ? error.message : String(error), ctx);
634
752
  }
@@ -638,12 +756,15 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
638
756
 
639
757
  pi.on("agent_settled", (_event, ctx) => {
640
758
  if (snapshot.config.enabled && retryQueued) abandonRun(ctx);
759
+ if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
641
760
  });
642
761
 
643
762
  pi.on("session_start", (event, ctx) => {
763
+ rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
644
764
  restoreActiveBranch(ctx, event.reason);
645
765
  refreshArtifactInvalidations(ctx);
646
766
  retryPendingPush(ctx);
767
+ if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
647
768
  updateUi(ctx);
648
769
  });
649
770
  pi.on("session_tree", (_event, ctx) => {
package/lib/git.ts CHANGED
@@ -26,7 +26,7 @@ import {
26
26
  type OwnedFileUpdate,
27
27
  } from "./durable.ts";
28
28
  import { planLegacyStorageMigration } from "./migration.ts";
29
- import { hashJson } from "./json.ts";
29
+ import { sameJson } from "./json.ts";
30
30
  import { validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
31
31
  import { createSessionRuntime, parseSessionRuntime, serializeSessionRuntime, type SessionRuntime, type Snapshot } from "./snapshot.ts";
32
32
  import { assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.ts";
@@ -490,13 +490,14 @@ function publishOwnedCohort(
490
490
  head: string | undefined,
491
491
  scopes: readonly StateScope[],
492
492
  operation: "persist" | "migrate",
493
+ push = true,
493
494
  ): { commit?: string; push?: GitPushResult } {
494
495
  let published = false;
495
496
  try {
496
497
  writeOwnedFileUpdates(updates, bases, root);
497
498
  published = true;
498
499
  const commit = commitOwnedFiles(root, updates, head, scopes, operation);
499
- return commit === undefined ? {} : { commit, push: pushGitCommit(root, commit) };
500
+ return commit === undefined ? {} : push ? { commit, push: pushGitCommit(root, commit) } : { commit };
500
501
  } catch (error) {
501
502
  if (published) {
502
503
  try {
@@ -528,7 +529,7 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
528
529
  updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
529
530
  const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head!, path).content === content)
530
531
  ? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
531
- if (existing && (!existing.runtime || hashJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }) !== hashJson(selected.view))) {
532
+ if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
532
533
  throw new Error("Existing Git runtime does not anchor the selected file cohort");
533
534
  }
534
535
  const publication = publishOwnedCohort(root, updates, current.files, current.head, [], "persist");
@@ -570,6 +571,7 @@ export function publishTemporalStateToGit(
570
571
  repositoryRoot: string,
571
572
  runtime?: SessionRuntime,
572
573
  sessionKey = sessionId,
574
+ push = true,
573
575
  ): { base: TemporalGitBase; commit?: string; push?: GitPushResult } {
574
576
  return withPublicationLock(repositoryRoot, (root) => {
575
577
  const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -583,17 +585,25 @@ export function publishTemporalStateToGit(
583
585
  if (runtimeOnly) {
584
586
  if (scopes.length !== 0) throw new Error("Runtime-only publication cannot write semantic scopes");
585
587
  const selected = loadTemporalRevision(cwd, sessionId, root, runtime!.meta.temporalRevision!, sessionKey);
586
- if (hashJson(selected.scopes) !== hashJson(view.scopes)) throw new Error("Runtime temporal reference does not match selected streams");
588
+ if (!sameJson(selected.scopes, view.scopes)) throw new Error("Runtime temporal reference does not match selected streams");
587
589
  }
588
590
  const { updates, changedScopes } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey);
589
591
  if (!runtimeOnly) includeUncommittedCohort(cwd, sessionId, root, current, updates, changedScopes, scopes, runtime !== undefined, sessionKey);
590
592
  if (updates.length === 0) return { base: current };
591
- const publication = publishOwnedCohort(root, updates, current.files, current.head, changedScopes, "persist");
593
+ const publication = publishOwnedCohort(root, updates, current.files, current.head, changedScopes, "persist", push);
592
594
  const nextFiles = temporalFileReceipts(current, updates);
593
595
  return { ...publication, base: { head: publication.commit ?? current.head, files: nextFiles } };
594
596
  });
595
597
  }
596
598
 
599
+ export function resolveGitPushDestination(repositoryRoot: string): { gitCommonDir: string; remote: string; ref: string } | undefined {
600
+ const root = assertRepositoryRoot(repositoryRoot);
601
+ const common = git(root, ["rev-parse", "--git-common-dir"]).stdout.trim();
602
+ const gitCommonDir = resolve(root, common);
603
+ const destination = pushDestination(root);
604
+ return destination === undefined ? undefined : { gitCommonDir, ...destination };
605
+ }
606
+
597
607
  function pushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
598
608
  const branchRef = currentBranchRef(repositoryRoot);
599
609
  const branch = branchRef.slice("refs/heads/".length);
@@ -621,6 +631,16 @@ export function isLocalGitRepository(repositoryRoot: string): boolean {
621
631
  }
622
632
 
623
633
  /** Push an already-created commit exactly; failures are publication state, not transition rejection. */
634
+ export function isGitCommitAncestor(repositoryRoot: string, ancestor: string, descendant: string): boolean {
635
+ const root = assertRepositoryRoot(repositoryRoot);
636
+ assertReadableRevision(root, ancestor);
637
+ assertReadableRevision(root, descendant);
638
+ const result = git(root, ["merge-base", "--is-ancestor", ancestor, descendant], { allowFailure: true });
639
+ if (result.status === 0) return true;
640
+ if (result.status === 1) return false;
641
+ throw new Error(`Cannot inspect Git commit ancestry: ${result.stderr || `exit ${result.status}`}`);
642
+ }
643
+
624
644
  export function pushGitCommit(repositoryRoot: string, commit: string): GitPushResult {
625
645
  try {
626
646
  const root = assertRepositoryRoot(repositoryRoot);
package/lib/history.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { hashJson, isJsonValue, isObject, validatePatch, type JsonObject } from "./json.ts";
2
+ import { isJsonValue, isObject, sameJson, validatePatch, type JsonObject } from "./json.ts";
3
3
  import type { ScopePatch, ScopedStates, StateScope } from "./state.ts";
4
4
 
5
5
  export const RECENT_TRANSITION_LIMIT = 7;
@@ -32,7 +32,7 @@ function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
32
32
  entries.push([key, null]);
33
33
  continue;
34
34
  }
35
- if (Object.hasOwn(before, key) && hashJson(before[key]) === hashJson(after[key])) continue;
35
+ if (Object.hasOwn(before, key) && sameJson(before[key], after[key])) continue;
36
36
  const previous = before[key];
37
37
  const next = after[key]!;
38
38
  entries.push([key, isObject(previous) && isObject(next) ? replayPatch(previous, next) : structuredClone(next)]);
package/lib/json.ts CHANGED
@@ -38,6 +38,30 @@ export function canonicalJson(value: JsonValue | unknown): string {
38
38
  return JSON.stringify(orderValue(value));
39
39
  }
40
40
 
41
+ export function sameJson(left: JsonValue | unknown, right: JsonValue | unknown): boolean {
42
+ if (left === right) {
43
+ if (!isJsonValue(left)) throw new Error("Values must be finite, acyclic JSON data");
44
+ return true;
45
+ }
46
+ if (!isJsonValue(left) || !isJsonValue(right)) throw new Error("Values must be finite, acyclic JSON data");
47
+ return equalJsonValues(left, right);
48
+ }
49
+
50
+ function equalJsonValues(left: JsonValue, right: JsonValue): boolean {
51
+ if (left === right) return true;
52
+ if (Array.isArray(left) || Array.isArray(right)) {
53
+ return Array.isArray(left) && Array.isArray(right) && left.length === right.length
54
+ && left.every((value, index) => equalJsonValues(value, right[index]!));
55
+ }
56
+ if (isObject(left) || isObject(right)) {
57
+ if (!isObject(left) || !isObject(right)) return false;
58
+ const keys = Object.keys(left);
59
+ return keys.length === Object.keys(right).length
60
+ && keys.every((key) => Object.hasOwn(right, key) && equalJsonValues(left[key]!, right[key]!));
61
+ }
62
+ return false;
63
+ }
64
+
41
65
  export function hashJson(value: JsonValue | unknown): string {
42
66
  return createHash("sha256").update(canonicalJson(value)).digest("hex");
43
67
  }
package/lib/memory.ts ADDED
@@ -0,0 +1,52 @@
1
+ import { isObject } from "./json.ts";
2
+ import type { MaterializedState, ScopedStates, StateScope } from "./state.ts";
3
+
4
+ export const MEMORY_PROMOTIONS_KEY = "memory_promotions";
5
+ export const MEMORY_PROMOTION_STATUSES = ["pending", "accepted", "failed", "unknown"] as const;
6
+ export type MemoryPromotionStatus = typeof MEMORY_PROMOTION_STATUSES[number];
7
+
8
+ export interface MemoryPromotionDiagnostic {
9
+ id: string;
10
+ status: MemoryPromotionStatus | "invalid";
11
+ owner?: string;
12
+ pointer?: string;
13
+ revision?: string;
14
+ error?: string;
15
+ }
16
+
17
+ function nonEmpty(value: unknown): string | undefined {
18
+ return typeof value === "string" && value.trim().length > 0 ? value : undefined;
19
+ }
20
+
21
+ /** Inspect the generic State Flow promotion convention without importing an external owner's schema. */
22
+ export function inspectMemoryPromotions(globalState: MaterializedState): MemoryPromotionDiagnostic[] {
23
+ const records = globalState.working[MEMORY_PROMOTIONS_KEY];
24
+ if (records === undefined) return [];
25
+ if (!isObject(records)) return [{ id: MEMORY_PROMOTIONS_KEY, status: "invalid", error: "promotion registry is not an object" }];
26
+ return Object.entries(records).sort(([left], [right]) => left.localeCompare(right)).map(([id, value]) => {
27
+ if (!isObject(value)) return { id, status: "invalid", error: "promotion record is not an object" };
28
+ const owner = nonEmpty(value.owner);
29
+ const pointer = nonEmpty(value.pointer);
30
+ const revision = nonEmpty(value.revision);
31
+ const error = nonEmpty(value.error);
32
+ const status = typeof value.status === "string" && (MEMORY_PROMOTION_STATUSES as readonly string[]).includes(value.status)
33
+ ? value.status as MemoryPromotionStatus
34
+ : undefined;
35
+ if (!status || !owner) return { id, status: "invalid", ...(owner ? { owner } : {}), ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: error ?? "promotion status/owner is invalid" };
36
+ if (status === "accepted" && (!pointer || !revision)) return { id, status: "invalid", owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: "accepted promotion requires pointer and revision" };
37
+ return { id, status, owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), ...(error ? { error } : {}) };
38
+ });
39
+ }
40
+
41
+ function hasSemanticMemory(state: MaterializedState, ignorePromotions: boolean): boolean {
42
+ if (Object.keys(state.contract).length > 0) return true;
43
+ return Object.keys(state.working).some((key) => !ignorePromotions || key !== MEMORY_PROMOTIONS_KEY);
44
+ }
45
+
46
+ export function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean> {
47
+ return {
48
+ global: hasSemanticMemory(states.global, true),
49
+ cwd: hasSemanticMemory(states.cwd, false),
50
+ session: hasSemanticMemory(states.session, false),
51
+ };
52
+ }