@llblab/pi-kit 0.5.2 → 0.7.0

package/node_modules/@llblab/pi-state-flow/docs/architecture.md

@@ -0,0 +1,188 @@
+# State Flow architecture
+
+## Purpose
+
+State Flow is a Pi extension that materializes compact, scoped semantic state across agent runs while preserving Pi's native session trace and tool loop. It is inspired by SKILL.state but uses its own temporal model, storage plane, artifact compiler, and publication lifecycle.
+
+The extension owns durable memory while enabled. Global semantic memory is always available; there are no ownership or global-memory feature switches.
+
+## Composition
+
+`index.ts` is the public export and extension composition boundary. Independent modules under `lib/` own one concern each and are mirrored by tests:
+
+- `state`, `json`: semantic shape, validation, recursive overlay and deletion.
+- `temporal`, `history`: causal boundaries, checkpoint/tail folding and hot history.
+- `durable`, `storage`, `git`: exact files, CAS publication, Git commits and restoration.
+- `snapshot`, `session`, `runtime`, `recovery`, `episode`: Pi branch/runtime lifecycle.
+- `transition`, `terminal`, `validation`, `context`: inference barriers and final reconciliation.
+- `artifact`, `acquisition`, `maintenance`, `skills`, `rehydration`: source routing and compilation.
+- `memory`: external promotion records and memory diagnostics.
+- `continuation`: native-header discovery, runtime-provenance inspection, deterministic recommendation, and host startup precedence.
+- `publication`: remote policy, durable CAS queue/store, cross-process leases, and asynchronous worker lifecycle.
+- `status`, `extension`: operator projection and Pi adapter wiring.
+
+## Semantic state
+
+Every materialized scope has exactly this shape:
+
+```json
+{
+  "artifacts": {},
+  "contract": {},
+  "working": {},
+  "response": ""
+}
+```
+
+- `artifacts` maps exact source paths to compiled routing metadata.
+- `contract` retains durable requirements, decisions, interfaces and rejected approaches.
+- `working` retains verified current facts, unresolved work and exact continuation.
+- `response` is the latest complete user-facing answer for the session scope.
+
+Effective state recursively overlays:
+
+```text
+global → CWD → session
+```
+
+Later scopes win. A scope-local `null` deletion removes only that scope's key and may reveal an inherited value. Scope represents applicability and ownership, never instruction authority.
+
+State Flow is the memory owner while enabled. Cross-project/user/environment knowledge belongs in global state, project-only knowledge in CWD, and branch/run continuation in session. Global availability is not a feature switch and does not authorize secrets, raw history, transient progress, speculative clutter, or unsupported assertions. Explicitly uncertain hypotheses remain eligible only when they can affect an open decision.
+
+## Temporal model
+
+All scopes participate in one active causal lineage. One accepted semantic transition receives one opaque identity shared by every changed scope. Sparse transitions do not create records for unchanged scopes.
+
+Each scope stores:
+
+```text
+checkpoint.json + patches.jsonl
+```
+
+The checkpoint is an older anchored materialization. The tail contains at most seven effective patches. On overflow, the oldest tail patch folds into the checkpoint before the new patch is appended.
+
+`state[n]`, `state.global[n]`, `state.cwd[n]` and `state.session[n]` resolve the same nth previous causal boundary. They are not independent per-scope patch counters. Pre-origin history is unavailable rather than empty.
+
+True semantic no-ops create no identity, commit or history step. A changed finalized response is semantic state and advances history.
+
+## Pi lifecycle
+
+`patch_state` is the sole mutation tool. It validates and publishes one scope patch immediately, then acts as an inference barrier. Pi executes no sibling tools from the same assistant response; the next inference sees rematerialized `state[0]`.
+
+`read_state` reads one cached effective or scoped projection at offsets zero through seven. It never publishes or advances history.
+
+Every successful enabled run ends with terminal reconciliation. A private `state_flow` comment may provide multi-scope transitions, followed by one blank line and the visible answer. An ordinary answer means an empty model patch but still updates session `response` when changed. Pi's finalized message at `turn_end` is authoritative for response reconciliation.
+
+The current user specification stays at user authority and appears only in synthetic user runtime context. State is fallible assistant-produced data. Completed trajectories leave model context at user-run boundaries, while Pi's full JSONL trace remains inspectable.
+
+## Storage and identity
+
+The default store is `<agentDir>/state-flow`, independent from Markdown discovery at `<agentDir>/knowledge`.
+
+Owned paths are:
+
+```text
+checkpoint.json
+patches.jsonl
+<cwd-key>/checkpoint.json
+<cwd-key>/patches.jsonl
+<cwd-key>/<session-key>/checkpoint.json
+<cwd-key>/<session-key>/patches.jsonl
+<cwd-key>/<session-key>/config.json
+<cwd-key>/<session-key>/meta.json
+```
+
+CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
+
+`config.json` owns branch runtime behavior. `meta.json` owns lineage, counters, identity, publication provenance and remote-publication policy. Pi checkpoints retain only an exact Git revision, an exact `file:<hash>` cohort reference, or a proven ordinary-disabled marker.
+
+All owned writes use same-directory atomic replacement, regular-file and symlink checks, prepared byte receipts and CAS validation. Unrelated files, staging and concurrent bytes are preserved. Rollback restores only bytes still matching the failed publisher's output.
+
+## Optional Git
+
+If Git is unavailable specifically through executable `ENOENT`, State Flow uses file-only persistence. File mode retains exact current materialization and proven hot history but offers no arbitrary cold revisions.
+
+With Git, each effective semantic cohort creates one local commit immediately through an isolated index. Git supplies cold history and exact branch restoration. Runtime `revision: "self"` resolves to the commit that owns the runtime record, never arbitrary `HEAD`. Runtime-only writes may use `temporalRevision` to select older semantic streams without rewinding live shared files.
+
+Installing Git over a file-only store adopts the exact current cohort without fabricating earlier history. Legacy layouts remain read-only historical inputs until explicitly migrated.
+
+## Remote publication
+
+Local acceptance and remote replication are separate.
+
+The persisted `remotePublication` policy is:
+
+- `turn-end`: default for new runtimes; local commits are immediate and the newest turn target is queued.
+- `off`: local commits only.
+- `transition`: synchronous compatibility behavior for legacy runtimes.
+
+A destination is identified by canonical Git common directory, remote and full ref. Queue files live beneath the Git common directory and are not semantic history.
+
+The queue uses exact commit targets, strict versioned JSON, symlink-safe atomic writes, CAS receipts and exclusive writer locks. A proven descendant may supersede an older target; divergent targets and changed destinations fail closed.
+
+After terminal acceptance, an asynchronous non-interactive worker pushes the newest target. Queue failure never rolls back semantic state or regenerates an answer. Failed and interrupted attempts remain retryable across restart. Destination-scoped worker leases prevent cross-process overlap, preserve live owners, recover proven-dead owners and use exact release tokens. Confirmation removes only the exact completed target; a newer descendant remains queued.
+
+## Artifact routing
+
+Markdown discovery recursively finds regular lowercase `*.md` beneath the configured Knowledge root, rejects symlinks, hashes opaque bytes and never injects source bodies.
+
+Artifact metadata requires:
+
+```json
+{
+  "description": "routing summary",
+  "hash": "sha256:<source bytes>",
+  "compiler": "artifact-v1"
+}
+```
+
+Compiler output may add arbitrary finite non-null JSON metadata. Known optional fields include `kind`, `compiled_at`, `tags` and `compilation`. Tags are unique trimmed non-empty strings and support deterministic candidate filtering, but never authorize reading.
+
+Freshness depends on source hash and compiler revision. New, changed, compiler-stale, malformed or explicitly refreshed sources become invalidations. Exact successful native Pi reads are correlated with current candidates; stale reads require same-path compiler output before trusted hash/compiler metadata is attached.
+
+Compilation is routing, not a substitute for source text. Full source is read only for a concrete unresolved gap, exact source/edit operation, invalidation, contradiction/failure, explicit request or bounded maintenance. The rehydration planner supports new-bootstrap, resume-bootstrap and later-step phases while limiting read count and source bytes without performing hidden I/O.
+
+Skills are CWD artifacts with stricter compilation: `kind: "skill"` and a non-empty compilation describing applicability, constraints and failure conditions. Their source bodies do not persist in state. Matching source hash and compiler metadata proves source-version consistency, not semantic fidelity, truth, or higher instruction authority.
+
+## Memory curation and promotion
+
+The optional packaged `state-flow-memory` Skill performs bounded explicit audits, scope narrowing, contradiction cleanup and external handoffs. It is not part of ordinary retention or background maintenance. Curation compiles a read Skill at CWD before accumulating global compilation obligations, writes and separately reads a migration destination before source deletion, then verifies the changed scope and effective overlay. Simultaneously pending CWD/global acquisitions use existing terminal multi-scope reconciliation; `patch_state` remains single-scope and separate calls are not atomic migration.
+
+External promotion remains a semantic two-phase handoff, not a memory-owner mode. Optional global `working.memory_promotions` entries record `pending`, `accepted`, `failed` or `unknown` status plus owner. Accepted records additionally require destination pointer and revision. Failed or uncertain promotion preserves the State Flow candidate; the only accepted copy is never deleted.
+
+## Session continuation
+
+The package exposes read-only host contracts that:
+
+- read only native JSONL headers, never transcript bodies;
+- inspect exact file/Git State Flow runtime provenance without mutation;
+- rank exact profile, CWD, Git common-directory, worktree, branch and transport identity;
+- fail closed for stopped, malformed, unavailable or ambiguous candidates;
+- preserve explicit new/resume and native picker precedence;
+- project new-bootstrap, resume-bootstrap and later-step rehydration phases.
+
+Pi 0.84.4 chooses or creates `SessionManager` before package resources and extensions load. Therefore native default auto-resume cannot be installed safely by this extension alone. The remaining host integration requires an upstream pre-session resolver hook or an SDK/launcher that invokes the advisory resolver before constructing the session.
+
+## Configuration
+
+`state-flow.json` is loaded once per extension load/reload:
+
+```json
+{
+  "directory": "~/.pi/agent/state-flow",
+  "autoStart": false,
+  "remotePublication": "turn-end"
+}
+```
+
+Unknown keys fail loading. State Flow memory ownership and global availability are fixed invariants and have no configuration options.
+
+## Observability
+
+`/state-flow-status` reports branch mode, runtime revision, temporal head/history depth, scope keys, patch tails, artifact freshness, memory-bearing scopes, external-promotion summaries, remote policy/queue state, pending publication and terminal retry state. Unavailable materialization is reported as unavailable, never fabricated as empty. Artifact source bodies are not read for status.
+
+## Validation boundaries
+
+Structural validation proves JSON shape, exact identity, causal lineage, freshness, CAS and publication invariants. A valid state, receipt, source hash, or compiler revision cannot prove semantic importance, truth, sufficient compilation, correct scope, useful curation, or historical deletion. Those remain model-judgment concerns evaluated separately from deterministic transport checks.
+
+The continuity requirement and deterministic evidence map is in [continuity-acceptance.md](continuity-acceptance.md). The executable temporal requirement map is in [temporal-acceptance.md](temporal-acceptance.md). Canonical remaining work is in [BACKLOG.md](../BACKLOG.md), and shipped outcomes belong in [CHANGELOG.md](../CHANGELOG.md).

package/node_modules/@llblab/pi-state-flow/docs/temporal-acceptance.md

@@ -0,0 +1,42 @@
+# Temporal acceptance
+
+The numbering below follows the twenty required tests in the temporal design correction. This is a maintained property-to-test map, not a second backlog or a substitute for running tests. Paths and quoted test names refer to a source checkout; tests are not shipped in the npm runtime package.
+
+## Required properties and witnesses
+
+1. **Zero patches:** `tests/temporal.test.ts` — “zero patches preserve the initial materialization without fabricating a past” compares current state with the checkpoint and rejects invented prior history.
+2. **One patch:** `tests/temporal.test.ts` — “one patch shifts current to history and reads return detached materializations” checks new current state and the preceding checkpoint state.
+3. **Seven patches:** `tests/temporal.test.ts` — “seven patches and repeated eighth-patch folding preserve every hot state exactly” compares every effective/scoped offset with retained snapshots at seven transitions.
+4. **Eighth-patch folding:** The same test explicitly checks checkpoint advancement through T1, its absorbed value, and the retained T2–T8 tail, alongside every hot offset.
+5. **Repeated folding:** The same test repeats through forty transitions. `tests/git.test.ts` — “temporal Git writer preserves all hot states through sparse folding and cold revision reads” exercises persisted representation too.
+6. **Sparse scopes share one target:** `tests/temporal.test.ts` — “sparse scope patches use effective boundaries, not each scope's mutation count” reproduces the T181–T184 example.
+7. **CWD indexing is not local-patch indexing:** That sparse test explicitly asserts both CWD offsets 1 and 2 equal C′. `tests/extension.test.ts` — “read_state lazily projects all hot offsets and scopes at one boundary without publication or Git calls” checks all 32 offset/scope combinations.
+8. **Shared multi-scope identity:** `tests/transition.test.ts` — “publishes one exact multi-scope replay cohort without explanatory windows or current-state DTOs” verifies one identity across changed scope records and exact replay.
+9. **Unchanged scopes stay stable:** The sparse temporal example checks global state at a boundary where only CWD/session change; “true no-ops do not enter history while response-only changes do” also checks that an unchanged session receives no new patch.
+10. **Historical deletion overlay:** `tests/temporal.test.ts` — “mixed sparse changes and deletion overlays match an independent snapshot oracle through compaction” explicitly checks session → CWD → global fallback and retained historical values.
+11. **Barrier shifts current to offset 1:** `tests/integration.test.ts` — “real Pi patch_state barriers rematerialize every scope before the next inference” observes the predecessor immediately after a barrier.
+12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects offset eight without a transition” adds model-tool access to the predecessor.
+13. **No automatic old full-state duplication:** `tests/context.test.ts` — “projects only the latest seven compact accepted transitions” rejects full-state records in transition context. The real-Pi barrier test requires exactly one current runtime projection per inference. Explicitly requested history remains ordinary tool-result trajectory, not eager snapshot injection.
+14. **Terminal changes are transitions:** `tests/terminal.test.ts` — “ordinary terminal answers commit once without retries and rotate the next request” and “reconciles response state with the finalized message after later handlers” verify accepted response persistence and replay.
+15. **True terminal no-op creates no fake history:** `tests/terminal.test.ts` — “identical finalized terminal state completes the runtime lifecycle without fake semantic history” checks unchanged semantic lineage/tails/step. Runtime lifecycle metadata may still change; omitting a memory patch is not a no-op when response changes.
+16. **Offset eight is outside hot history:** `tests/temporal.test.ts` — “hot range and unproven pre-migration history are explicit read boundaries”; the real-Pi history-reader test also exercises native tool rejection without a transition.
+17. **Cold Git history remains recoverable:** `tests/git.test.ts` — “temporal Git writer preserves all hot states through sparse folding and cold revision reads” loads older committed states without moving the worktree.
+18. **Tree/resume select the correct lineage:** `tests/integration.test.ts` — “real Pi preserves branch-local state through compaction, tree navigation, stop, and restart” and “real Pi old tree branch stop and resume preserve selected semantics without rewinding shared files”.
+19. **Stop changes config, not semantic history:** `tests/git.test.ts` — “session config/meta publish atomically with temporal files and config-only stop creates no semantic step”; `tests/runtime.test.ts` verifies old-branch stop without semantic writes and failed-restore stop/resume.
+20. **Lossless current-state migration:** `tests/migration.test.ts` — “migration anchors exact current materializations and never replays explanatory journals”; `tests/git.test.ts` — “migrates all three current snapshots in one isolated commit without losing semantic or cold history”; runtime tests cover revision-linked migration with malformed explanatory history.
+
+## Additional preservation boundaries
+
+- `tests/durable.test.ts`, `tests/git.test.ts`, and `tests/migration.test.ts` cover owned regular files, raw-byte rollback, prepared-output receipts, stale/omitted-scope CAS, linked-worktree publication exclusion, unrelated staging, and exact-commit push retry.
+- `tests/recovery.test.ts` and `tests/runtime.test.ts` distinguish invalid immutable targets from transient publication failures, preserve checkpoint provenance, and prevent invalid-only recovery from becoming permission to replace runtime.
+- `tests/context.test.ts` and `tests/extension.test.ts` prohibit process queries during ordinary context/history reads. `tests/transition.test.ts` rejects stale staging even when semantic values coincide across different causal boundaries.
+- `tests/status.test.ts` distinguishes selected temporal history depth from retained per-scope tails and unavailable materialization from an empty state.
+- `tests/storage.test.ts` covers Git absence, exact file-cohort references, file CAS/rollback and shared writer exclusion. `tests/runtime.test.ts` and the native Pi Git-absent lifecycle test cover file-pointer restart, immediate barriers, finalized response, config-only stop, and unavailable-reference provenance. File-only mode supplies current/hot state; Git-dependent cold and arbitrary branch recovery require Git and the original committed objects.
+- File-to-Git tests in `tests/storage.test.ts`, `tests/runtime.test.ts` and the native Pi lifecycle cover full-cohort adoption over unborn/stale HEAD, exact inherited bytes, unchanged semantic step/hot history, rollback, staging preservation and subsequent configured-remote publication. `tests/git.test.ts` rejects omitted uncommitted streams; working-tree equality alone cannot prove a Git commit contains the selected state.
+- `tests/config.test.ts` covers optional agent configuration, path precedence/expansion, invalid input, load-time caching and read-only behavior. Session tests and native Pi distinguish configured new-session auto-start from branch-local resume/tree/stop. The global default is manual; CWD materialization alone no longer grants automatic activation.
+
+## Validation and limits
+
+Run `npm run validate` in the source checkout. Run context/DAG validation and `npm pack --dry-run --ignore-scripts` for documentation, dependency direction, and package inventory after an applicable full validation.
+
+Real-Pi tests use the actual Pi SDK and native tool loop with a deterministic faux model and temporary Git repositories. They do not prove that an unconstrained model always follows the memory protocol, nor do they migrate production Knowledge or publish the real repository. Complete native trace remains available; normal model projection retains only the required active context. Cooperative locking and conflict preservation are not kernel-atomic multi-file transactions against nonparticipating writers. Test counts do not establish exhaustive equivalence with every removed predecessor assertion.

package/node_modules/@llblab/pi-state-flow/index.ts

@@ -1,4 +1,166 @@
+export {
+  ArtifactReadTracker,
+  decideArtifactAcquisition,
+  type ArtifactAcquisitionDecision,
+  type ArtifactAcquisitionIntent,
+  type ArtifactAcquisitionOptions,
+  type ArtifactAcquisitionReason,
+  type SuccessfulArtifactRead
+} from "./lib/acquisition.ts";
+export {
+  classifyArtifactFreshness,
+  hashArtifactSource,
+  isArtifactHash,
+  isArtifactMetadata,
+  isArtifactRegistry,
+  ORDINARY_ARTIFACT_COMPILER,
+  planArtifactInvalidation,
+  selectArtifactsByTags,
+  updateArtifactRegistry,
+  validateArtifactMetadata,
+  validateArtifactRegistry,
+  type ArtifactCompilationUpdate,
+  type ArtifactCompilerOutput,
+  type ArtifactFreshness,
+  type ArtifactInvalidationOptions,
+  type ArtifactInvalidationPlan,
+  type ArtifactInvalidationReason,
+  type ArtifactInvalidationRequest,
+  type ArtifactMetadata,
+  type ArtifactRegistry,
+  type ArtifactSourceIdentity
+} from "./lib/artifact.ts";
+export {
+  buildContinuationCandidates,
+  discoverNativeSessionHeaders,
+  inspectStateFlowContinuationProvenance,
+  readNativeSessionHeader,
+  recommendContinuationFromProvenance,
+  resolveContinuationStartup,
+  type ContinuationCandidateProvenance,
+  type ContinuationCandidateSummary,
+  type ContinuationHostContext,
+  type ContinuationHostIntent,
+  type ContinuationProjectIdentity,
+  type ContinuationRecommendation,
+  type ContinuationRecommender,
+  type ContinuationSessionCandidate,
+  type ContinuationStartupDecision,
+  type ContinuationTransport,
+  type NativeSessionHeader
+} from "./lib/continuation.ts";
+export {
+  discoverGlobalMarkdownSources,
+  getKnowledgeRoot,
+  GlobalMarkdownDiscovery,
+  type ArtifactSourceCandidate,
+  type GlobalMarkdownDiscoveryResult
+} from "./lib/discovery.ts";
+export {
+  captureTemporalFileBases,
+  cwdScopeKey,
+  getDurableRepositoryRoot,
+  isStateFlowOwnedPath,
+  loadScopeStream,
+  parseScopeStream,
+  serializeScopeStream, sessionRuntimePaths, sessionScopeKey,
+  sessionStorageKey, temporalScopePaths,
+  temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths
+} from "./lib/durable.ts";
+export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
+export {
+  captureTemporalGitBase,
+  isGitCommitAncestor,
+  loadTemporalRevision,
+  migrateLegacyStorageToGit,
+  publishTemporalStateToGit,
+  pushGitCommit,
+  resolveGitPushDestination, type GitPushResult, type TemporalGitBase,
+  type TemporalRevisionLoad
+} from "./lib/git.ts";
+export {
+  createAcceptedTransition,
+  projectRecentTransitionsWithLimit,
+  RECENT_TRANSITION_LIMIT,
+  validateRecentTransition, type AcceptedTransition, type RecentScopePatch,
+  type RecentTransition,
+  type RecentTransitionWindow
+} from "./lib/history.ts";
 export { applyPatch, canonicalJson, hashJson, isObject, validatePatch } from "./lib/json.ts";
 export type { JsonObject, JsonValue } from "./lib/json.ts";
-export { emptyState, isStateDocument, type StateDocument } from "./lib/state.ts";
-export { default } from "./lib/extension.ts";
+export {
+  DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS,
+  DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES,
+  DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS,
+  planArtifactMaintenance,
+  type ArtifactMaintenanceOptions,
+  type ArtifactMaintenancePlan,
+  type ArtifactMaintenanceRequest
+} from "./lib/maintenance.ts";
+export {
+  inspectMemoryPromotions, MEMORY_PROMOTION_STATUSES, MEMORY_PROMOTIONS_KEY, retainedMemoryScopes,
+  type MemoryPromotionDiagnostic,
+  type MemoryPromotionStatus
+} from "./lib/memory.ts";
+export {
+  acquirePublicationWorkerLease,
+  beginPublicationAttempt,
+  coalescePublicationTarget,
+  confirmPublicationTarget,
+  createPublicationQueue,
+  failPublicationAttempt,
+  loadPublicationQueue,
+  parsePublicationQueue,
+  parseRemotePublicationPolicyDocument,
+  publicationQueuePath,
+  recoverPublicationQueue,
+  remotePublicationDestinationKey,
+  removePublicationQueue,
+  resolveRemotePublicationPolicy,
+  runPublicationWorker,
+  savePublicationQueue,
+  serializePublicationQueue,
+  serializeRemotePublicationPolicyDocument,
+  validatePublicationQueue,
+  type CommitAncestor,
+  type PublicationPush,
+  type PublicationQueueReceipt,
+  type PublicationQueueState,
+  type PublicationQueueStatus,
+  type PublicationWorkerLease,
+  type PublicationWorkerResult,
+  type RemotePublicationDestination,
+  type RemotePublicationMode,
+  type RemotePublicationPolicy,
+  type RemotePublicationPolicyDocument
+} from "./lib/publication.ts";
+export {
+  planKnowledgeRehydration,
+  type RehydrationOptions,
+  type RehydrationPhase,
+  type RehydrationPlan,
+  type RehydrationRead,
+  type RehydrationRoute
+} from "./lib/rehydration.ts";
+export { TemporalRuntime } from "./lib/runtime.ts";
+export {
+  hasCompiledSkillArtifact,
+  hashSkillSource,
+  migrateLegacySkillCompilations,
+  SKILL_ARTIFACT_COMPILER,
+  type SuccessfulSkillRead
+} from "./lib/skills.ts";
+export {
+  emptyState,
+  isMaterializedState,
+  isStateDocument,
+  overlayStates,
+  updateMaterializedArtifacts,
+  type MaterializedState, type ScopedPatch,
+  type ScopedStates, type ScopePatch, type SemanticTransition,
+  type StateDocument,
+  type StatePatch,
+  type StateScope,
+  type TerminalTransition
+} from "./lib/state.ts";
+export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";

package/node_modules/@llblab/pi-state-flow/lib/acquisition.ts

@@ -0,0 +1,138 @@
+import {
+	classifyArtifactFreshness,
+	type ArtifactInvalidationReason,
+	type ArtifactInvalidationRequest,
+	type ArtifactSourceIdentity,
+} from "./artifact.ts";
+import { isObject } from "./json.ts";
+
+/** Why the caller is considering source-body acquisition. */
+export type ArtifactAcquisitionIntent =
+	| "routine"
+	| "new-session"
+	| "relevant-gap"
+	| "exact-source"
+	| "exact-edit"
+	| "contradiction-or-failure"
+	| "explicit-request"
+	| "maintenance";
+
+export type ArtifactAcquisitionReason =
+	| ArtifactInvalidationReason
+	| "materialized-gap"
+	| "exact-source"
+	| "exact-edit"
+	| "contradiction-or-failure"
+	| "explicit-request"
+	| "maintenance";
+
+export type ArtifactAcquisitionDecision =
+	| { kind: "use-materialized"; reason: "no-concrete-need" | "materialized-sufficient" }
+	| { kind: "read-source"; reason: ArtifactAcquisitionReason };
+
+export interface ArtifactAcquisitionOptions {
+	intent: ArtifactAcquisitionIntent;
+	/** Caller-assessed semantic sufficiency; only relevant to a concrete relevant gap. */
+	materializedSufficient?: boolean;
+	explicitRefresh?: boolean;
+}
+
+/** A successful read correlated to a runtime-observed invalidation candidate. */
+export interface SuccessfulArtifactRead extends ArtifactInvalidationRequest {}
+
+interface PendingRead {
+	toolName: string;
+	args: unknown;
+}
+
+function readPath(toolName: unknown, args: unknown): string | undefined {
+	return toolName === "read" && isObject(args) && typeof args.path === "string"
+		? args.path
+		: undefined;
+}
+
+/** Correlate successful read-tool executions with the current ordinary artifact invalidation plan. */
+export class ArtifactReadTracker {
+	readonly successful = new Map<string, SuccessfulArtifactRead>();
+	readonly #pending = new Map<string, PendingRead>();
+	readonly #candidates = new Map<string, ArtifactInvalidationRequest>();
+
+	setCandidates(candidates: Iterable<ArtifactInvalidationRequest>): void {
+		this.#candidates.clear();
+		for (const candidate of candidates) this.#candidates.set(candidate.path, structuredClone(candidate));
+	}
+
+	clear(): void {
+		this.successful.clear();
+		this.#pending.clear();
+	}
+
+	recordStart(toolCallId: string, toolName: string, args: unknown): void {
+		this.#record(toolCallId, toolName, args);
+	}
+
+	recordCall(toolCallId: string, toolName: string, input: unknown): void {
+		this.#record(toolCallId, toolName, input);
+	}
+
+	recordEnd(toolCallId: string, toolName: string, isError: boolean): void {
+		const pending = this.#pending.get(toolCallId);
+		this.#pending.delete(toolCallId);
+		if (isError || !pending || toolName !== pending.toolName) return;
+		const path = readPath(pending.toolName, pending.args);
+		if (path === undefined) return;
+		const candidate = this.#candidates.get(path);
+		if (candidate !== undefined) this.successful.set(path, structuredClone(candidate));
+	}
+
+	#record(toolCallId: string, toolName: string, args: unknown): void {
+		if (toolName !== "read") {
+			this.#pending.delete(toolCallId);
+			return;
+		}
+		this.#pending.set(toolCallId, { toolName, args });
+	}
+}
+
+/**
+ * Apply one materialized-first source acquisition policy.
+ *
+ * Freshness invalidation always wins. Otherwise routine use and a new session
+ * stay on materialized state; only a concrete source need permits rereading.
+ */
+export function decideArtifactAcquisition(
+	source: ArtifactSourceIdentity,
+	metadata: unknown,
+	compiler: string,
+	options: ArtifactAcquisitionOptions,
+): ArtifactAcquisitionDecision {
+	const freshness = classifyArtifactFreshness(
+		source,
+		metadata,
+		compiler,
+		options.explicitRefresh ?? false,
+	);
+	if (freshness.kind === "requires-compilation") {
+		return { kind: "read-source", reason: freshness.reason };
+	}
+
+	switch (options.intent) {
+		case "routine":
+		case "new-session":
+			return { kind: "use-materialized", reason: "no-concrete-need" };
+		case "relevant-gap":
+			return options.materializedSufficient === true
+				? { kind: "use-materialized", reason: "materialized-sufficient" }
+				: { kind: "read-source", reason: "materialized-gap" };
+		case "exact-source":
+			return { kind: "read-source", reason: "exact-source" };
+		case "exact-edit":
+			return { kind: "read-source", reason: "exact-edit" };
+		case "contradiction-or-failure":
+			return { kind: "read-source", reason: "contradiction-or-failure" };
+		case "explicit-request":
+			return { kind: "read-source", reason: "explicit-request" };
+		case "maintenance":
+			return { kind: "read-source", reason: "maintenance" };
+	}
+}