@llblab/pi-kit 0.18.1 → 0.19.0

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

@@ -1,20 +1,17 @@
 export { ArtifactReadTracker, decideArtifactAcquisition, type ArtifactAcquisitionDecision, type ArtifactAcquisitionIntent, type ArtifactAcquisitionOptions, type ArtifactAcquisitionReason, type SuccessfulArtifactRead } from "./lib/acquisition.ts";
-export { classifyArtifactFreshness, compileArtifact, hashArtifactSource, isArtifactHash, isArtifactMetadata, isArtifactRegistry, ORDINARY_ARTIFACT_COMPILER, parseArtifactProvenanceRegistry, planArtifactInvalidation, projectArtifactForModel, projectArtifactsForModel, pruneArtifactProvenance, selectArtifactsByTags, serializeArtifactProvenanceRegistry, updateArtifactProvenance, updateArtifactRegistry, validateArtifactMetadata, validateArtifactRegistry, type ArtifactCompilationUpdate, type ArtifactCompilerOutput, type ArtifactFreshness, type ArtifactInvalidationNotice, type ArtifactInvalidationOptions, type ArtifactInvalidationPlan, type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactMetadata, type ArtifactProvenance, type ArtifactProvenanceRegistry, type ArtifactRegistry, type ArtifactSourceIdentity, type CompiledArtifact } from "./lib/artifact.ts";
+export { classifyArtifactCompilationNeed, compileArtifact, hashArtifactSource, isArtifactHash, isArtifactMetadata, isArtifactRegistry, ORDINARY_ARTIFACT_COMPILER, parseArtifactProvenanceRegistry, projectArtifactForModel, projectArtifactsForModel, pruneArtifactProvenance, selectArtifactsByTags, serializeArtifactProvenanceRegistry, updateArtifactProvenance, updateArtifactRegistry, validateArtifactMetadata, validateArtifactRegistry, type ArtifactCompilationUpdate, type ArtifactCompilerOutput, type ArtifactCompilationNeed, type ArtifactInvalidationNotice, type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactMetadata, type ArtifactProvenance, type ArtifactProvenanceRegistry, type ArtifactRegistry, type ArtifactSourceIdentity, type CompiledArtifact } 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, parseScopeProvenance, parseScopeStream, serializeScopeProvenance, serializeScopeStream, sessionRuntimePaths, sessionScopeKey, sessionStorageKey, temporalScopePaths, temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths } from "./lib/durable.ts";
-export { default, MAX_FALLBACK_ATTEMPTS, 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 { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
+export { backupCurrentStateFlowFiles } from "./lib/git.ts";
+export { createAcceptedTransition, DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, projectRecentTransitionsWithLimit, 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 { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath, type StateFlowDiagnosticBlock, type StateFlowDiagnosticCategory, type StateFlowDiagnosticRecord } from "./lib/logging.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 { retainedMemoryScopes } from "./lib/memory.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 { hasCompiledSkillArtifact, hashSkillSource, SKILL_ARTIFACT_COMPILER, type SuccessfulSkillRead } from "./lib/skills.ts";
 export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts, type AtomicScopePatches, type MaterializedState, type ScopedPatch, type ScopedStates, type ScopePatch, type SemanticTransition, type StateDocument, type StatePatch, type StateScope, type TerminalTransition } from "./lib/state.ts";
 export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID, type StateFlowTelegramAdapter, type StateFlowTelegramButton, type StateFlowTelegramCallbackContext, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramModules, type StateFlowTelegramPort, type StateFlowTelegramSectionContext, type StateFlowTelegramSectionModule, type StateFlowTelegramSnapshot, type StateFlowTelegramView } from "./lib/telegram.ts";
 export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";

package/node_modules/@llblab/pi-state-flow/dist/index.js

@@ -1,19 +1,16 @@
 export { ArtifactReadTracker, decideArtifactAcquisition } from "./lib/acquisition.js";
-export { classifyArtifactFreshness, compileArtifact, hashArtifactSource, isArtifactHash, isArtifactMetadata, isArtifactRegistry, ORDINARY_ARTIFACT_COMPILER, parseArtifactProvenanceRegistry, planArtifactInvalidation, projectArtifactForModel, projectArtifactsForModel, pruneArtifactProvenance, selectArtifactsByTags, serializeArtifactProvenanceRegistry, updateArtifactProvenance, updateArtifactRegistry, validateArtifactMetadata, validateArtifactRegistry } from "./lib/artifact.js";
+export { classifyArtifactCompilationNeed, compileArtifact, hashArtifactSource, isArtifactHash, isArtifactMetadata, isArtifactRegistry, ORDINARY_ARTIFACT_COMPILER, parseArtifactProvenanceRegistry, projectArtifactForModel, projectArtifactsForModel, pruneArtifactProvenance, selectArtifactsByTags, serializeArtifactProvenanceRegistry, updateArtifactProvenance, updateArtifactRegistry, validateArtifactMetadata, validateArtifactRegistry } from "./lib/artifact.js";
 export { buildContinuationCandidates, discoverNativeSessionHeaders, inspectStateFlowContinuationProvenance, readNativeSessionHeader, recommendContinuationFromProvenance, resolveContinuationStartup } from "./lib/continuation.js";
-export { discoverGlobalMarkdownSources, getKnowledgeRoot, GlobalMarkdownDiscovery } from "./lib/discovery.js";
 export { captureTemporalFileBases, cwdScopeKey, getDurableRepositoryRoot, isStateFlowOwnedPath, loadScopeStream, parseScopeProvenance, parseScopeStream, serializeScopeProvenance, serializeScopeStream, sessionRuntimePaths, sessionScopeKey, sessionStorageKey, temporalScopePaths, temporalStateFileUpdates } from "./lib/durable.js";
-export { default, MAX_FALLBACK_ATTEMPTS, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME } from "./lib/extension.js";
-export { captureTemporalGitBase, isGitCommitAncestor, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit, pushGitCommit, resolveGitPushDestination } from "./lib/git.js";
-export { createAcceptedTransition, projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT, validateRecentTransition } from "./lib/history.js";
+export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME } from "./lib/extension.js";
+export { backupCurrentStateFlowFiles } from "./lib/git.js";
+export { createAcceptedTransition, DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, projectRecentTransitionsWithLimit, validateRecentTransition } from "./lib/history.js";
 export { applyPatch, canonicalJson, hashJson, isObject, validatePatch } from "./lib/json.js";
 export { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath } from "./lib/logging.js";
-export { DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS, DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES, DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS, planArtifactMaintenance } from "./lib/maintenance.js";
-export { inspectMemoryPromotions, MEMORY_PROMOTION_STATUSES, MEMORY_PROMOTIONS_KEY, retainedMemoryScopes } from "./lib/memory.js";
-export { acquirePublicationWorkerLease, beginPublicationAttempt, coalescePublicationTarget, confirmPublicationTarget, createPublicationQueue, failPublicationAttempt, loadPublicationQueue, parsePublicationQueue, parseRemotePublicationPolicyDocument, publicationQueuePath, recoverPublicationQueue, remotePublicationDestinationKey, removePublicationQueue, resolveRemotePublicationPolicy, runPublicationWorker, savePublicationQueue, serializePublicationQueue, serializeRemotePublicationPolicyDocument, validatePublicationQueue } from "./lib/publication.js";
+export { retainedMemoryScopes } from "./lib/memory.js";
 export { planKnowledgeRehydration } from "./lib/rehydration.js";
 export { TemporalRuntime } from "./lib/runtime.js";
-export { hasCompiledSkillArtifact, hashSkillSource, migrateLegacySkillCompilations, SKILL_ARTIFACT_COMPILER } from "./lib/skills.js";
+export { hasCompiledSkillArtifact, hashSkillSource, SKILL_ARTIFACT_COMPILER } from "./lib/skills.js";
 export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts } from "./lib/state.js";
 export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID } from "./lib/telegram.js";
 export { advanceTemporalState, readTemporalState } from "./lib/temporal.js";

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

@@ -14,7 +14,7 @@ export interface ArtifactAcquisitionOptions {
     /** Caller-assessed semantic sufficiency; only relevant to a concrete relevant gap. */
     materializedSufficient?: boolean;
     explicitRefresh?: boolean;
-    /** Runtime-owned freshness evidence retained beside the semantic artifact. */
+    /** Runtime-owned compilation evidence retained beside the semantic artifact. */
     provenance?: unknown;
 }
 /** A successful read correlated to a runtime-observed invalidation candidate. */
@@ -33,7 +33,7 @@ export declare class ArtifactReadTracker {
 /**
  * Apply one materialized-first source acquisition policy.
  *
- * Freshness invalidation always wins. Otherwise routine use and a new session
+ * Required recompilation always wins. Otherwise routine use and a new session
  * stay on materialized state; only a concrete source need permits rereading.
  */
 export declare function decideArtifactAcquisition(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, options: ArtifactAcquisitionOptions): ArtifactAcquisitionDecision;

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

@@ -1,4 +1,4 @@
-import { classifyArtifactFreshness, } from "./artifact.js";
+import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint, } from "./artifact.js";
 import { isObject } from "./json.js";
 function readPath(toolName, args) {
     return toolName === "read" && isObject(args) && typeof args.path === "string"
@@ -34,27 +34,40 @@ export class ArtifactReadTracker {
         if (path === undefined)
             return;
         const candidate = this.#candidates.get(path);
-        if (candidate !== undefined)
-            this.successful.set(path, structuredClone(candidate));
+        if (candidate === undefined || pending.fingerprint === undefined)
+            return;
+        const observation = inspectRegisteredArtifactPaths([path])[0];
+        if (observation?.kind !== "present" || !sameArtifactSourceFingerprint(pending.fingerprint, observation.fingerprint))
+            return;
+        const finalObservation = inspectRegisteredArtifactPaths([path])[0];
+        if (finalObservation?.kind !== "present" || !sameArtifactSourceFingerprint(observation.fingerprint, finalObservation.fingerprint))
+            return;
+        this.successful.set(path, structuredClone({ ...candidate, sourceFingerprint: finalObservation.fingerprint }));
     }
     #record(toolCallId, toolName, args) {
         if (toolName !== "read") {
             this.#pending.delete(toolCallId);
             return;
         }
-        this.#pending.set(toolCallId, { toolName, args });
+        const path = readPath(toolName, args);
+        const observation = path !== undefined && this.#candidates.has(path) ? inspectRegisteredArtifactPaths([path])[0] : undefined;
+        this.#pending.set(toolCallId, {
+            toolName,
+            args,
+            ...(observation?.kind === "present" ? { fingerprint: observation.fingerprint } : {}),
+        });
     }
 }
 /**
  * Apply one materialized-first source acquisition policy.
  *
- * Freshness invalidation always wins. Otherwise routine use and a new session
+ * Required recompilation always wins. Otherwise routine use and a new session
  * stay on materialized state; only a concrete source need permits rereading.
  */
 export function decideArtifactAcquisition(source, metadata, compiler, options) {
-    const freshness = classifyArtifactFreshness(source, metadata, compiler, options.explicitRefresh ?? false, options.provenance);
-    if (freshness.kind === "requires-compilation") {
-        return { kind: "read-source", reason: freshness.reason };
+    const need = classifyArtifactCompilationNeed(source, metadata, compiler, options.explicitRefresh ?? false, options.provenance);
+    if (need.kind === "requires-compilation") {
+        return { kind: "read-source", reason: need.reason };
     }
     switch (options.intent) {
         case "routine":

package/node_modules/@llblab/pi-state-flow/dist/lib/artifact.d.ts

@@ -1,10 +1,31 @@
 import { type JsonObject } from "./json.ts";
-/** Current compiler protocol for ordinary source artifacts such as Knowledge Markdown. */
+export interface ArtifactSourceFingerprint {
+    size: number;
+    mtimeNs: string;
+}
+export declare function parseArtifactSourceFingerprint(value: unknown): ArtifactSourceFingerprint | undefined;
+export declare function sameArtifactSourceFingerprint(left: ArtifactSourceFingerprint, right: ArtifactSourceFingerprint): boolean;
+export type ArtifactSourceObservation = {
+    path: string;
+    kind: "present";
+    fingerprint: ArtifactSourceFingerprint;
+} | {
+    path: string;
+    kind: "missing";
+} | {
+    path: string;
+    kind: "unavailable";
+    reason: string;
+};
+/** Inspect only exact registered artifact paths without reading source bodies or traversing directories. */
+export declare function inspectRegisteredArtifactPaths(paths: Iterable<string>): ArtifactSourceObservation[];
+/** Current compiler protocol for ordinary registered source artifacts. */
 export declare const ORDINARY_ARTIFACT_COMPILER = "artifact-v1";
-/** Freshness fields that runtime-owned scope metadata may retain per artifact path. */
+/** Compilation evidence that runtime-owned scope metadata may retain per artifact path. */
 export interface ArtifactProvenance {
     /** Retained value; absent means unavailable, malformed means fail closed. */
     sourceHash?: unknown;
+    sourceFingerprint?: unknown;
     compilerRevision?: unknown;
     compiledAt?: unknown;
     /** Internal marker for an uninterpretable retained entry; every dependent capability fails closed. */
@@ -17,7 +38,7 @@ export type ArtifactProvenanceRegistry = Record<string, ArtifactProvenance>;
  * `hash`, `compiler`, and `compiled_at` remain accepted only as retired embedded
  * provenance input from pre-0.7 state; they are consumed as compatibility evidence
  * and stripped from model projection. New compilations keep semantic fields here and
- * runtime-owned freshness in the scope `meta.json` provenance registry.
+ * runtime-owned compilation evidence in the scope `meta.json` provenance registry.
  */
 export type ArtifactMetadata = JsonObject & {
     description: string;
@@ -30,14 +51,20 @@ export type ArtifactMetadata = JsonObject & {
 };
 /** Artifact source paths are the canonical registry keys. */
 export type ArtifactRegistry = JsonObject & Record<string, ArtifactMetadata>;
-/** Source identity is sufficient for freshness decisions; it never contains the source body. */
+/** Source identity is sufficient for compilation decisions; it never contains the source body. */
+export type ArtifactScope = "global" | "cwd" | "session";
 export interface ArtifactSourceIdentity {
     path: string;
-    hash: string;
+    /** Exact semantic owner selected from the effective global → CWD → session overlay. */
+    scope?: ArtifactScope;
+    /** Transitional legacy content identity; generic maintenance uses the filesystem fingerprint instead. */
+    hash?: string;
+    /** Stable filesystem evidence observed across the successful source read. */
+    sourceFingerprint?: ArtifactSourceFingerprint;
 }
 export type ArtifactInvalidationReason = "new" | "source-changed" | "compiler-changed" | "invalid-metadata" | "explicit-refresh";
-export type ArtifactFreshness = {
-    kind: "fresh";
+export type ArtifactCompilationNeed = {
+    kind: "current";
 } | {
     kind: "requires-compilation";
     reason: ArtifactInvalidationReason;
@@ -48,19 +75,9 @@ export interface ArtifactInvalidationRequest extends ArtifactSourceIdentity {
 /** Model-visible invalidation projection: paths and reasons only, never source identity. */
 export interface ArtifactInvalidationNotice {
     path: string;
+    scope?: ArtifactScope;
     reason: ArtifactInvalidationReason;
 }
-export interface ArtifactInvalidationPlan {
-    fresh: ArtifactSourceIdentity[];
-    requiresCompilation: ArtifactInvalidationRequest[];
-    removed: string[];
-}
-export interface ArtifactInvalidationOptions {
-    /** Refresh every source, or only paths in the supplied set. */
-    explicitRefresh?: boolean | ReadonlySet<string>;
-    /** Explicit absence evidence supplied by the source owner, not inferred from a partial candidate set. */
-    removed?: readonly string[];
-}
 /** Trusted compilation input; embedded timestamps are accepted here, but never in model patches. */
 export type ArtifactCompilerOutput = JsonObject & {
     description: string;
@@ -90,10 +107,8 @@ export declare function isArtifactRegistry(value: unknown): value is ArtifactReg
 export declare function parseArtifactProvenanceRegistry(value: unknown, context?: string): ArtifactProvenanceRegistry;
 /** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
 export declare function serializeArtifactProvenanceRegistry(registry: Readonly<ArtifactProvenanceRegistry>): JsonObject;
-/** Classify freshness from semantic state and runtime provenance without acquiring the source body. */
-export declare function classifyArtifactFreshness(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, explicitRefresh?: boolean, provenance?: unknown): ArtifactFreshness;
-/** Produce a deterministic acquisition plan from path/hash candidates and retained evidence. */
-export declare function planArtifactInvalidation(sources: readonly ArtifactSourceIdentity[], registry: Readonly<Record<string, unknown>>, compiler: string, options?: ArtifactInvalidationOptions, provenance?: Readonly<ArtifactProvenanceRegistry>): ArtifactInvalidationPlan;
+/** Decide whether retained compilation evidence requires source reacquisition. */
+export declare function classifyArtifactCompilationNeed(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, explicitRefresh?: boolean, provenance?: unknown): ArtifactCompilationNeed;
 /** Split one compiler output into model-visible semantics and runtime-owned provenance. */
 export declare function compileArtifact(update: ArtifactCompilationUpdate): CompiledArtifact;
 /** Merge one compilation/removal cohort into the runtime-owned provenance registry. */
@@ -106,5 +121,6 @@ export declare function updateArtifactRegistry(registry: ArtifactRegistry, updat
 export declare function validateModelArtifactPatch(patch: JsonObject): void;
 /** Strip retained runtime bookkeeping from one model-visible artifact entry. */
 export declare function projectArtifactForModel(entry: unknown): unknown;
-/** Strip retained runtime bookkeeping from a model-visible artifact registry. */
-export declare function projectArtifactsForModel(registry: Readonly<ArtifactRegistry>): ArtifactRegistry;
+export type ArtifactModelHints = Readonly<Record<string, string | readonly string[]>>;
+/** Strip retained runtime bookkeeping and add deterministic runtime-only guidance. */
+export declare function projectArtifactsForModel(registry: Readonly<ArtifactRegistry>, hints?: ArtifactModelHints): ArtifactRegistry;

package/node_modules/@llblab/pi-state-flow/dist/lib/artifact.js

@@ -1,8 +1,57 @@
 import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { containsNull, isJsonValue, isObject } from "./json.js";
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
-const MODEL_FORBIDDEN_PROVENANCE_FIELDS = ["hash", "compiler", "sourceHash", "compilerRevision", "compiledAt", "source_hash_verified"];
-/** Current compiler protocol for ordinary source artifacts such as Knowledge Markdown. */
+const MODEL_FORBIDDEN_PROVENANCE_FIELDS = ["hash", "compiler", "sourceHash", "sourceFingerprint", "compilerRevision", "compiledAt", "source_hash_verified"];
+export function parseArtifactSourceFingerprint(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    if (Object.keys(candidate).sort().join(",") !== "mtimeNs,size"
+        || !Number.isSafeInteger(candidate.size) || candidate.size < 0
+        || typeof candidate.mtimeNs !== "string" || !/^-?\d+$/.test(candidate.mtimeNs))
+        return undefined;
+    return { size: candidate.size, mtimeNs: candidate.mtimeNs };
+}
+export function sameArtifactSourceFingerprint(left, right) {
+    return left.size === right.size && left.mtimeNs === right.mtimeNs;
+}
+function artifactSourceErrorCode(error) {
+    return error instanceof Error && "code" in error
+        ? error.code
+        : undefined;
+}
+/** Inspect only exact registered artifact paths without reading source bodies or traversing directories. */
+export function inspectRegisteredArtifactPaths(paths) {
+    return [...new Set(paths)].sort().map((path) => {
+        if (!isAbsolute(path) || resolve(path) !== path) {
+            return { path, kind: "unavailable", reason: "artifact path is not canonical and absolute" };
+        }
+        let metadata;
+        try {
+            metadata = lstatSync(path, { bigint: true });
+        }
+        catch (error) {
+            const code = artifactSourceErrorCode(error);
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return { path, kind: "missing" };
+            return { path, kind: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+        }
+        if (!metadata.isFile() || metadata.isSymbolicLink()) {
+            return { path, kind: "unavailable", reason: "artifact source is not a regular non-symlink file" };
+        }
+        if (metadata.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+            return { path, kind: "unavailable", reason: "artifact source size exceeds the supported range" };
+        }
+        return {
+            path,
+            kind: "present",
+            fingerprint: { size: Number(metadata.size), mtimeNs: metadata.mtimeNs.toString() },
+        };
+    });
+}
+/** Current compiler protocol for ordinary registered source artifacts. */
 export const ORDINARY_ARTIFACT_COMPILER = "artifact-v1";
 export function hashArtifactSource(source) {
     return `sha256:${createHash("sha256").update(source).digest("hex")}`;
@@ -88,9 +137,12 @@ function validateSourceIdentity(source) {
     if (typeof source.path !== "string" || source.path.trim().length === 0) {
         throw new Error("Artifact source path must be non-empty");
     }
-    if (!isArtifactHash(source.hash)) {
+    if (source.hash !== undefined && !isArtifactHash(source.hash)) {
         throw new Error(`Artifact source at ${source.path} must have a sha256:<64 lowercase hex characters> hash`);
     }
+    if (source.sourceFingerprint !== undefined && parseArtifactSourceFingerprint(source.sourceFingerprint) === undefined) {
+        throw new Error(`Artifact source fingerprint at ${source.path} is invalid`);
+    }
 }
 function validateCompilerRevision(compiler, path) {
     if (typeof compiler !== "string" || compiler.trim().length === 0) {
@@ -99,13 +151,6 @@ function validateCompilerRevision(compiler, path) {
             : `Artifact compiler revision at ${path} must be non-empty`);
     }
 }
-function refreshRequested(path, explicitRefresh) {
-    if (explicitRefresh === true)
-        return true;
-    if (!explicitRefresh || typeof explicitRefresh !== "object" || typeof explicitRefresh.has !== "function")
-        return false;
-    return explicitRefresh.has(path);
-}
 function isProvenanceEntry(value) {
     return isObject(value) && (value.malformed === undefined || value.malformed === true);
 }
@@ -123,13 +168,14 @@ export function parseArtifactProvenanceRegistry(value, context = "Artifact prove
             registry[path] = { malformed: true };
             continue;
         }
-        const known = new Set(["sourceHash", "compilerRevision", "compiledAt"]);
+        const known = new Set(["sourceHash", "sourceFingerprint", "compilerRevision", "compiledAt"]);
         if (Object.keys(entry).some((key) => !known.has(key))) {
             registry[path] = { malformed: true };
             continue;
         }
         registry[path] = {
             ...(Object.hasOwn(entry, "sourceHash") ? { sourceHash: entry.sourceHash } : {}),
+            ...(Object.hasOwn(entry, "sourceFingerprint") ? { sourceFingerprint: entry.sourceFingerprint } : {}),
             ...(Object.hasOwn(entry, "compilerRevision") ? { compilerRevision: entry.compilerRevision } : {}),
             ...(Object.hasOwn(entry, "compiledAt") ? { compiledAt: entry.compiledAt } : {}),
         };
@@ -145,6 +191,8 @@ export function serializeArtifactProvenanceRegistry(registry) {
         const fields = {};
         if (entry.sourceHash !== undefined)
             fields.sourceHash = entry.sourceHash;
+        if (entry.sourceFingerprint !== undefined)
+            fields.sourceFingerprint = entry.sourceFingerprint;
         if (entry.compilerRevision !== undefined)
             fields.compilerRevision = entry.compilerRevision;
         if (entry.compiledAt !== undefined)
@@ -158,17 +206,14 @@ export function serializeArtifactProvenanceRegistry(registry) {
 function invalidField(value, validate) {
     return value !== undefined && !validate(value);
 }
-const INVALID_EVIDENCE = Symbol("invalid-evidence");
 /** Later authority wins per field; absent runtime evidence falls back to retired embedded values. */
 function fieldEvidence(entry, field, legacy) {
-    if (entry?.malformed === true)
-        return INVALID_EVIDENCE;
     if (entry !== undefined && Object.hasOwn(entry, field))
         return entry[field];
     return legacy;
 }
-/** Classify freshness from semantic state and runtime provenance without acquiring the source body. */
-export function classifyArtifactFreshness(source, metadata, compiler, explicitRefresh = false, provenance) {
+/** Decide whether retained compilation evidence requires source reacquisition. */
+export function classifyArtifactCompilationNeed(source, metadata, compiler, explicitRefresh = false, provenance) {
     validateSourceIdentity(source);
     validateCompilerRevision(compiler);
     if (metadata === undefined)
@@ -176,16 +221,27 @@ export function classifyArtifactFreshness(source, metadata, compiler, explicitRe
     if (!isArtifactMetadata(metadata))
         return { kind: "requires-compilation", reason: "invalid-metadata" };
     const entry = isProvenanceEntry(provenance) ? provenance : undefined;
-    const runtime = entry?.malformed === true;
-    const sourceHash = runtime ? INVALID_EVIDENCE : fieldEvidence(entry, "sourceHash", metadata.hash);
-    if (sourceHash === INVALID_EVIDENCE || invalidField(sourceHash, (value) => isArtifactHash(value))) {
+    if ((provenance !== undefined && entry === undefined) || entry?.malformed === true) {
         return { kind: "requires-compilation", reason: "invalid-metadata" };
     }
-    if (typeof sourceHash === "string" && sourceHash !== source.hash) {
-        return { kind: "requires-compilation", reason: "source-changed" };
+    if (source.sourceFingerprint !== undefined) {
+        const retained = parseArtifactSourceFingerprint(entry?.sourceFingerprint);
+        if (retained === undefined)
+            return { kind: "requires-compilation", reason: "invalid-metadata" };
+        if (!sameArtifactSourceFingerprint(source.sourceFingerprint, retained))
+            return { kind: "requires-compilation", reason: "source-changed" };
+    }
+    if (source.sourceFingerprint === undefined || source.hash !== undefined) {
+        // Explicit current-hash observations, including Skills, retain their identity contract.
+        const sourceHash = fieldEvidence(entry, "sourceHash", metadata.hash);
+        if (invalidField(sourceHash, isArtifactHash))
+            return { kind: "requires-compilation", reason: "invalid-metadata" };
+        if (source.hash !== undefined && typeof sourceHash === "string" && sourceHash !== source.hash) {
+            return { kind: "requires-compilation", reason: "source-changed" };
+        }
     }
-    const compilerRevision = runtime ? INVALID_EVIDENCE : fieldEvidence(entry, "compilerRevision", metadata.compiler);
-    if (compilerRevision === INVALID_EVIDENCE || invalidField(compilerRevision, (value) => typeof value === "string" && value.trim().length > 0)) {
+    const compilerRevision = fieldEvidence(entry, "compilerRevision", metadata.compiler);
+    if (invalidField(compilerRevision, (value) => typeof value === "string" && value.trim().length > 0)) {
         return { kind: "requires-compilation", reason: "invalid-metadata" };
     }
     if (typeof compilerRevision === "string" && compilerRevision !== compiler) {
@@ -193,40 +249,7 @@ export function classifyArtifactFreshness(source, metadata, compiler, explicitRe
     }
     if (explicitRefresh)
         return { kind: "requires-compilation", reason: "explicit-refresh" };
-    return { kind: "fresh" };
-}
-/** Produce a deterministic acquisition plan from path/hash candidates and retained evidence. */
-export function planArtifactInvalidation(sources, registry, compiler, options = {}, provenance = {}) {
-    if (!isObject(registry))
-        throw new Error("Artifacts must be a path-keyed JSON object");
-    validateCompilerRevision(compiler);
-    const ordered = [...sources].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
-    const seen = new Set();
-    const fresh = [];
-    const requiresCompilation = [];
-    for (const source of ordered) {
-        if (seen.has(source.path))
-            throw new Error(`Duplicate artifact source path: ${source.path}`);
-        seen.add(source.path);
-        const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
-        const entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
-        const freshness = classifyArtifactFreshness(source, metadata, compiler, refreshRequested(source.path, options.explicitRefresh), entry);
-        const identity = { path: source.path, hash: source.hash };
-        if (freshness.kind === "fresh")
-            fresh.push(identity);
-        else
-            requiresCompilation.push({ ...identity, reason: freshness.reason });
-    }
-    if (options.removed !== undefined && !Array.isArray(options.removed))
-        throw new Error("Removed artifact paths must be an array");
-    const removed = [...new Set(options.removed ?? [])];
-    for (const path of removed) {
-        if (typeof path !== "string" || path.trim().length === 0)
-            throw new Error("Removed artifact paths must be non-empty");
-        if (seen.has(path))
-            throw new Error(`Artifact source cannot be both present and removed: ${path}`);
-    }
-    return { fresh, requiresCompilation, removed: removed.filter((path) => Object.hasOwn(registry, path)).sort() };
+    return { kind: "current" };
 }
 /** Split one compiler output into model-visible semantics and runtime-owned provenance. */
 export function compileArtifact(update) {
@@ -242,7 +265,8 @@ export function compileArtifact(update) {
     return {
         semantic,
         provenance: {
-            sourceHash: update.source.hash,
+            ...(update.source.hash === undefined ? {} : { sourceHash: update.source.hash }),
+            ...(update.source.sourceFingerprint === undefined ? {} : { sourceFingerprint: structuredClone(update.source.sourceFingerprint) }),
             compilerRevision: update.compiler,
             ...(typeof update.output.compiled_at === "string" ? { compiledAt: update.output.compiled_at } : {}),
         },
@@ -299,7 +323,7 @@ export function updateArtifactRegistry(registry, updates, removed = []) {
     return next;
 }
 /** Runtime-owned artifact fields that never belong in ordinary model context. */
-const RUNTIME_ARTIFACT_FIELDS = [...MODEL_FORBIDDEN_PROVENANCE_FIELDS, "compiled_at"];
+const RUNTIME_ARTIFACT_FIELDS = [...MODEL_FORBIDDEN_PROVENANCE_FIELDS, "compiled_at", "hint"];
 /** Validate authored fields only: legacy retained evidence stays readable but cannot be model-edited. */
 export function validateModelArtifactPatch(patch) {
     for (const [path, entry] of Object.entries(patch)) {
@@ -307,7 +331,7 @@ export function validateModelArtifactPatch(patch) {
             continue; // Whole-artifact deletion and materialized shape belong to the transition owner.
         const field = RUNTIME_ARTIFACT_FIELDS.find((field) => Object.hasOwn(entry, field));
         if (field !== undefined)
-            throw new Error(`Artifact patch at ${path} cannot set runtime-owned provenance field ${field}`);
+            throw new Error(`Artifact patch at ${path} cannot set runtime-owned field ${field}`);
     }
 }
 /** Strip retained runtime bookkeeping from one model-visible artifact entry. */
@@ -319,12 +343,18 @@ export function projectArtifactForModel(entry) {
         delete projected[field];
     return projected;
 }
-/** Strip retained runtime bookkeeping from a model-visible artifact registry. */
-export function projectArtifactsForModel(registry) {
+/** Strip retained runtime bookkeeping and add deterministic runtime-only guidance. */
+export function projectArtifactsForModel(registry, hints = {}) {
     const projected = {};
     for (const [path, entry] of Object.entries(registry)) {
+        const modelEntry = projectArtifactForModel(entry);
+        const values = (Array.isArray(hints[path]) ? hints[path] : [hints[path]])
+            .filter((value) => typeof value === "string" && value.trim().length > 0);
+        const hint = [...new Set(values)].sort().join("\n");
+        if (hint.length > 0 && isObject(modelEntry))
+            modelEntry.hint = hint;
         Object.defineProperty(projected, path, {
-            value: projectArtifactForModel(entry),
+            value: modelEntry,
             enumerable: true,
             configurable: true,
             writable: true,

package/node_modules/@llblab/pi-state-flow/dist/lib/compaction.d.ts

@@ -1,11 +1,11 @@
 import type { CompactionResult } from "@earendil-works/pi-coding-agent";
-export declare const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its durable revision and projected separately; use the retained native entries for subsequent work.";
+export declare const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its retained semantic boundary and projected separately; use the retained native entries for subsequent work.";
 /** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
 export declare const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24000;
 export interface StateFlowCompactionDetails {
     version: 1;
     owner: "state-flow";
-    revision: string;
+    boundary: string;
     step: number;
 }
 export interface StateFlowCompactionPlan {
@@ -21,6 +21,7 @@ type ActiveEntry = {
         role?: unknown;
         stopReason?: unknown;
         content?: unknown;
+        timestamp?: unknown;
     };
 };
 export declare function shouldRequestStateFlowCompaction(usage: {
@@ -33,7 +34,7 @@ export declare function shouldRequestStateFlowCompaction(usage: {
  */
 export declare function hasCompactionSizedTranscript(entries: readonly ActiveEntry[]): boolean;
 /** Retain the complete latest accepted user iteration without hiding foreign extension context. */
-export declare function planStateFlowCompaction(entries: readonly ActiveEntry[], revision: string, step: number): StateFlowCompactionPlan | undefined;
+export declare function planStateFlowCompaction(entries: readonly ActiveEntry[], boundary: string, step: number, runAnchorTimestamp: number | undefined): StateFlowCompactionPlan | undefined;
 /** Customize only the extension-owned manual request and only while its planned leaf remains selected. */
 export declare function stateFlowCompactionResult(plan: StateFlowCompactionPlan, marker: string, event: {
     reason: "manual" | "threshold" | "overflow";

package/node_modules/@llblab/pi-state-flow/dist/lib/compaction.js

@@ -1,5 +1,5 @@
 import { estimateTokens } from "@earendil-works/pi-agent-core";
-export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its durable revision and projected separately; use the retained native entries for subsequent work.";
+export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its retained semantic boundary and projected separately; use the retained native entries for subsequent work.";
 /** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
 export const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24_000;
 function stateFlowEntry(entry) {
@@ -29,8 +29,8 @@ export function hasCompactionSizedTranscript(entries) {
     return false;
 }
 /** Retain the complete latest accepted user iteration without hiding foreign extension context. */
-export function planStateFlowCompaction(entries, revision, step) {
-    if (!/^[0-9a-f]{40,64}$/.test(revision) && !/^file:[0-9a-f]{64}$/.test(revision))
+export function planStateFlowCompaction(entries, boundary, step, runAnchorTimestamp) {
+    if (boundary.trim().length === 0 || typeof runAnchorTimestamp !== "number" || !Number.isFinite(runAnchorTimestamp))
         return undefined;
     if (!Number.isSafeInteger(step) || step < 0 || entries.length === 0)
         return undefined;
@@ -39,18 +39,18 @@ export function planStateFlowCompaction(entries, revision, step) {
         || entries[terminal]?.message?.stopReason === "error"
         || entries[terminal]?.message?.stopReason === "length")
         return undefined;
-    let keep = terminal;
-    while (keep >= 0 && !(entries[keep]?.type === "message" && entries[keep]?.message?.role === "user"))
-        keep--;
-    if (keep < 0)
+    // Steering is part of the same run; an absent or colliding timestamp cannot prove its first entry.
+    const isRunAnchor = (entry) => entry.type === "message" && entry.message?.role === "user" && entry.message.timestamp === runAnchorTimestamp;
+    const keep = entries.findIndex(isRunAnchor);
+    if (keep < 0 || keep > terminal || entries.findLastIndex(isRunAnchor) !== keep)
         return undefined;
-    if (entries.slice(0, keep).some((entry) => entry.type === "custom" && !stateFlowEntry(entry)))
+    if (entries.slice(0, keep).some((entry) => entry.type === "custom_message" || (entry.type === "custom" && !stateFlowEntry(entry))))
         return undefined;
     const firstKeptEntryId = entries[keep]?.id;
     const leafId = entries.at(-1)?.id;
     if (typeof firstKeptEntryId !== "string" || typeof leafId !== "string")
         return undefined;
-    return { leafId, firstKeptEntryId, details: { version: 1, owner: "state-flow", revision, step } };
+    return { leafId, firstKeptEntryId, details: { version: 1, owner: "state-flow", boundary, step } };
 }
 /** Customize only the extension-owned manual request and only while its planned leaf remains selected. */
 export function stateFlowCompactionResult(plan, marker, event) {

package/node_modules/@llblab/pi-state-flow/dist/lib/config.d.ts

@@ -8,7 +8,7 @@ export interface StateFlowConfig {
     logging: boolean;
     /** Show successful patch_state arguments in the interactive tool row. */
     showSuccessfulPatches: boolean;
-    remotePublication?: "off" | "turn-end" | "transition";
+    historyLimit: number;
 }
 /** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
 export declare function loadStateFlowConfig(agentDir?: string, repositoryRoot?: string): StateFlowConfig;