@agent-plan/core 0.2.23 → 0.2.24

package/dist/read-tracking.d.ts

@@ -1,49 +1,86 @@
 /**
- * Per-session, ordered context-read enforcement for agent lifecycle operations.
+ * Session-scoped, ordered context-read enforcement for agent lifecycle operations.
  *
- * An agent must read the exact task, then its parent phase, then its parent
- * feature with full=true before it can start, resume, or switch to that task.
- * Compact list/identity reads never count. The state is process-local and is
- * cleared on pause, switch, and session startup by the harness adapters.
- *
- * Linked requirements remain a separate explicit-read gate. They are recorded
- * only through the requirement list tool and never by an entity read.
+ * The first complete read for a task must be task(full) → phase(full) →
+ * feature(full), with linked requirements read independently. A persisted
+ * sessionInfo attestation may satisfy later checks in the same session while
+ * every entity's updatedAt remains at or before its attestation timestamp.
  */
+type SessionInfoEntry = {
+    sessionId: string;
+    createdAt: string;
+};
+type ReadTrackedEntity = {
+    updatedAt: string;
+    sessionInfo?: SessionInfoEntry[];
+};
 export type ContextReadEligibility = {
     eligible: boolean;
     reason: string;
 };
-/** Record a full feature read. */
+export interface SessionContextReadInput {
+    sessionId: string;
+    taskId: string;
+    phaseId: string;
+    featureId?: string;
+    task?: ReadTrackedEntity;
+    phase?: ReadTrackedEntity;
+    feature?: ReadTrackedEntity;
+    requirements?: Array<ReadTrackedEntity & {
+        id: string;
+    }>;
+    requirementIds?: string[];
+}
+/** Record a full feature read in the default compatibility session. */
 export declare function markFeatureRead(featureId: string): void;
-/** Record a full phase read. The parent feature is intentionally not implied. */
+/** Record a full feature read for an explicit harness session. */
+export declare function markFeatureReadForSessionId(sessionId: string, featureId: string): void;
+/** Record a full phase read in the default compatibility session. */
 export declare function markPhaseRead(phaseId: string, _featureId?: string): void;
-/** Record a full task read. Its parent phase and feature are intentionally not implied. */
+/** Record a full phase read for an explicit harness session. */
+export declare function markPhaseReadForSessionId(sessionId: string, phaseId: string): void;
+/** Record a full task read in the default compatibility session. */
 export declare function markTaskRead(taskId: string, _phaseId?: string, _featureId?: string): void;
-/** Record that a requirement was explicitly read via the requirement list tool. */
+/** Record a full task read for an explicit harness session. */
+export declare function markTaskReadForSessionId(sessionId: string, taskId: string): void;
+/** Record that a requirement was explicitly read in the default session. */
 export declare function markRequirementRead(requirementId: string): void;
+/** Record that a requirement was explicitly read for an explicit session. */
+export declare function markRequirementReadForSessionId(sessionId: string, requirementId: string): void;
 /**
- * Verify the required task(full) → phase(full) → feature(full) order for one
- * exact task lineage. Orphan phases do not require a feature read.
+ * Evaluate exact in-memory read ordering first, then a persisted attestation
+ * for the same session and current entity revisions. A previously persisted
+ * but now stale attestation always wins over stale in-memory ordering.
  */
+export declare function contextReadEligibilityForSession(input: SessionContextReadInput): ContextReadEligibility;
+/** Return true only when the persisted attestation covers the current revisions. */
+export declare function hasValidSessionAttestation(input: SessionContextReadInput): boolean;
+/** Compatibility check for the default session and in-memory reads only. */
 export declare function contextReadEligibility(taskId: string, phaseId: string, featureId?: string): ContextReadEligibility;
+/** Legacy parent-read check retained for callers that only need independent parent state. */
+export declare function hasReadParents(featureId: string | undefined, phaseId: string): boolean;
 /**
- * Legacy parent-read check retained for callers that only need to know whether
- * both parent entities have been read. Lifecycle gates must use
- * contextReadEligibility so the task and ordering cannot be bypassed.
+ * Whether linked requirements are read in memory or have valid persisted
+ * attestations for the current session and entity revisions.
  */
-export declare function hasReadParents(featureId: string | undefined, phaseId: string): boolean;
-/** Whether every linked requirement has been explicitly read. */
+export declare function hasReadRequirementsForSession(sessionId: string, requirementIds: string[], requirements?: Array<ReadTrackedEntity & {
+    id: string;
+}>): boolean;
+/** Legacy requirement check for the default compatibility session. */
 export declare function hasReadRequirements(requirementIds: string[]): boolean;
-/** Clear all read state so later lifecycle work requires fresh context. */
-export declare function invalidateReads(): void;
+/** Clear one session's read state, or all state for legacy callers. */
+export declare function invalidateReads(sessionId?: string): void;
+/** Initialize an explicit session without clearing other harness sessions. */
+export declare function startReadSession(sessionId: string): void;
 /** Compatibility advisory for non-lifecycle callers. */
 export declare function parentReadAdvisory(featureId: string | undefined, phaseId: string): string;
 /** Advisory text for the separate linked-requirements gate. */
 export declare function requirementReadAdvisory(requirementIds: string[]): string;
-/** Snapshot for diagnostics and tests. */
-export declare function readTrackingSnapshot(): {
+/** Snapshot for diagnostics. */
+export declare function readTrackingSnapshot(sessionId?: string): {
     features: string[];
     phases: string[];
     requirements: string[];
 };
+export {};
 //# sourceMappingURL=read-tracking.d.ts.map

package/dist/read-tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAeF,kCAAkC;AAClC,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAExE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAmBlH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAItF;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAErE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,IAAI,CAQtC;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxE;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,IAAI;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAMvG"}
+{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"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"}

package/dist/read-tracking.js

@@ -1,46 +1,82 @@
 /**
- * Per-session, ordered context-read enforcement for agent lifecycle operations.
+ * Session-scoped, ordered context-read enforcement for agent lifecycle operations.
  *
- * An agent must read the exact task, then its parent phase, then its parent
- * feature with full=true before it can start, resume, or switch to that task.
- * Compact list/identity reads never count. The state is process-local and is
- * cleared on pause, switch, and session startup by the harness adapters.
- *
- * Linked requirements remain a separate explicit-read gate. They are recorded
- * only through the requirement list tool and never by an entity read.
+ * The first complete read for a task must be task(full) → phase(full) →
+ * feature(full), with linked requirements read independently. A persisted
+ * sessionInfo attestation may satisfy later checks in the same session while
+ * every entity's updatedAt remains at or before its attestation timestamp.
  */
-let state = {
+const DEFAULT_SESSION_ID = "__default__";
+const newState = () => ({
     tasks: new Map(),
     phases: new Map(),
     features: new Map(),
     requirements: new Set(),
     nextSequence: 0,
-};
-function record(map, id) {
+});
+const states = new Map([[DEFAULT_SESSION_ID, newState()]]);
+function normalizeSessionId(sessionId) {
+    return sessionId?.trim() || DEFAULT_SESSION_ID;
+}
+function stateFor(sessionId) {
+    const key = normalizeSessionId(sessionId);
+    let state = states.get(key);
+    if (!state) {
+        state = newState();
+        states.set(key, state);
+    }
+    return state;
+}
+function record(map, id, state) {
     state.nextSequence += 1;
     map.set(id, state.nextSequence);
 }
-/** Record a full feature read. */
+function markTaskReadForSession(sessionId, taskId) {
+    const state = stateFor(sessionId);
+    record(state.tasks, taskId, state);
+}
+function markPhaseReadForSession(sessionId, phaseId) {
+    const state = stateFor(sessionId);
+    record(state.phases, phaseId, state);
+}
+function markFeatureReadForSession(sessionId, featureId) {
+    const state = stateFor(sessionId);
+    record(state.features, featureId, state);
+}
+/** Record a full feature read in the default compatibility session. */
 export function markFeatureRead(featureId) {
-    record(state.features, featureId);
+    markFeatureReadForSession(DEFAULT_SESSION_ID, featureId);
+}
+/** Record a full feature read for an explicit harness session. */
+export function markFeatureReadForSessionId(sessionId, featureId) {
+    markFeatureReadForSession(sessionId, featureId);
 }
-/** Record a full phase read. The parent feature is intentionally not implied. */
+/** Record a full phase read in the default compatibility session. */
 export function markPhaseRead(phaseId, _featureId) {
-    record(state.phases, phaseId);
+    markPhaseReadForSession(DEFAULT_SESSION_ID, phaseId);
 }
-/** Record a full task read. Its parent phase and feature are intentionally not implied. */
+/** Record a full phase read for an explicit harness session. */
+export function markPhaseReadForSessionId(sessionId, phaseId) {
+    markPhaseReadForSession(sessionId, phaseId);
+}
+/** Record a full task read in the default compatibility session. */
 export function markTaskRead(taskId, _phaseId, _featureId) {
-    record(state.tasks, taskId);
+    markTaskReadForSession(DEFAULT_SESSION_ID, taskId);
+}
+/** Record a full task read for an explicit harness session. */
+export function markTaskReadForSessionId(sessionId, taskId) {
+    markTaskReadForSession(sessionId, taskId);
 }
-/** Record that a requirement was explicitly read via the requirement list tool. */
+/** Record that a requirement was explicitly read in the default session. */
 export function markRequirementRead(requirementId) {
-    state.requirements.add(requirementId);
+    stateFor(DEFAULT_SESSION_ID).requirements.add(requirementId);
 }
-/**
- * Verify the required task(full) → phase(full) → feature(full) order for one
- * exact task lineage. Orphan phases do not require a feature read.
- */
-export function contextReadEligibility(taskId, phaseId, featureId) {
+/** Record that a requirement was explicitly read for an explicit session. */
+export function markRequirementReadForSessionId(sessionId, requirementId) {
+    stateFor(sessionId).requirements.add(requirementId);
+}
+function orderedEligibility(sessionId, taskId, phaseId, featureId) {
+    const state = stateFor(sessionId);
     const taskSequence = state.tasks.get(taskId);
     if (taskSequence === undefined) {
         return { eligible: false, reason: "Read this exact task with full=true first." };
@@ -57,38 +93,87 @@ export function contextReadEligibility(taskId, phaseId, featureId) {
     }
     return { eligible: true, reason: "" };
 }
+function validSessionInfo(entity, sessionId) {
+    const entry = entity?.sessionInfo?.find((candidate) => candidate.sessionId === sessionId);
+    return Boolean(entity && entry && entity.updatedAt <= entry.createdAt);
+}
+function persistedEligibility(input) {
+    if (!validSessionInfo(input.task, input.sessionId) || !validSessionInfo(input.phase, input.sessionId))
+        return false;
+    if (input.featureId && !validSessionInfo(input.feature, input.sessionId))
+        return false;
+    const requirementIds = input.requirementIds ?? [];
+    return requirementIds.every((id) => validSessionInfo(input.requirements?.find((requirement) => requirement.id === id), input.sessionId));
+}
+function hasStoredSessionAttestation(input) {
+    const entities = [input.task, input.phase, input.feature, ...(input.requirements ?? [])];
+    return entities.some((entity) => entity?.sessionInfo?.some((entry) => entry.sessionId === input.sessionId));
+}
 /**
- * Legacy parent-read check retained for callers that only need to know whether
- * both parent entities have been read. Lifecycle gates must use
- * contextReadEligibility so the task and ordering cannot be bypassed.
+ * Evaluate exact in-memory read ordering first, then a persisted attestation
+ * for the same session and current entity revisions. A previously persisted
+ * but now stale attestation always wins over stale in-memory ordering.
  */
+export function contextReadEligibilityForSession(input) {
+    const ordered = orderedEligibility(input.sessionId, input.taskId, input.phaseId, input.featureId);
+    if (ordered.eligible)
+        return ordered;
+    if (input.task && input.phase && persistedEligibility(input))
+        return { eligible: true, reason: "" };
+    if (input.task && input.phase && hasStoredSessionAttestation(input)) {
+        return { eligible: false, reason: "Context changed since the last session read; reread the exact task, phase, feature, and linked requirements." };
+    }
+    return ordered;
+}
+/** Return true only when the persisted attestation covers the current revisions. */
+export function hasValidSessionAttestation(input) {
+    return persistedEligibility(input);
+}
+/** Compatibility check for the default session and in-memory reads only. */
+export function contextReadEligibility(taskId, phaseId, featureId) {
+    return orderedEligibility(DEFAULT_SESSION_ID, taskId, phaseId, featureId);
+}
+/** Legacy parent-read check retained for callers that only need independent parent state. */
 export function hasReadParents(featureId, phaseId) {
-    const phaseOk = state.phases.has(phaseId);
-    const featureOk = featureId ? state.features.has(featureId) : true;
-    return phaseOk && featureOk;
+    const state = stateFor(DEFAULT_SESSION_ID);
+    return state.phases.has(phaseId) && (!featureId || state.features.has(featureId));
 }
-/** Whether every linked requirement has been explicitly read. */
+/**
+ * Whether linked requirements are read in memory or have valid persisted
+ * attestations for the current session and entity revisions.
+ */
+export function hasReadRequirementsForSession(sessionId, requirementIds, requirements = []) {
+    const state = stateFor(sessionId);
+    return requirementIds.every((id) => state.requirements.has(id) || validSessionInfo(requirements.find((requirement) => requirement.id === id), sessionId));
+}
+/** Legacy requirement check for the default compatibility session. */
 export function hasReadRequirements(requirementIds) {
-    return requirementIds.every((id) => state.requirements.has(id));
-}
-/** Clear all read state so later lifecycle work requires fresh context. */
-export function invalidateReads() {
-    state = {
-        tasks: new Map(),
-        phases: new Map(),
-        features: new Map(),
-        requirements: new Set(),
-        nextSequence: 0,
-    };
+    return requirementIds.every((id) => stateFor(DEFAULT_SESSION_ID).requirements.has(id));
+}
+/** Clear one session's read state, or all state for legacy callers. */
+export function invalidateReads(sessionId) {
+    if (sessionId) {
+        states.delete(normalizeSessionId(sessionId));
+        stateFor(sessionId);
+        return;
+    }
+    states.clear();
+    states.set(DEFAULT_SESSION_ID, newState());
+}
+/** Initialize an explicit session without clearing other harness sessions. */
+export function startReadSession(sessionId) {
+    stateFor(sessionId);
 }
 /** Compatibility advisory for non-lifecycle callers. */
 export function parentReadAdvisory(featureId, phaseId) {
-    if (hasReadParents(featureId, phaseId))
+    const state = stateFor(DEFAULT_SESSION_ID);
+    if (state.phases.has(phaseId) && (!featureId || state.features.has(featureId)))
         return "";
     return "\n\n⚠️ READ REQUIRED before proceeding: read the parent phase and feature with full=true.";
 }
 /** Advisory text for the separate linked-requirements gate. */
 export function requirementReadAdvisory(requirementIds) {
+    const state = stateFor(DEFAULT_SESSION_ID);
     if (requirementIds.length === 0)
         return "";
     const unread = requirementIds.filter((id) => !state.requirements.has(id));
@@ -96,8 +181,9 @@ export function requirementReadAdvisory(requirementIds) {
         return "";
     return "\n\n⚠️ REQUIREMENTS READ REQUIRED before proceeding: read the requirements linked to this phase and feature.";
 }
-/** Snapshot for diagnostics and tests. */
-export function readTrackingSnapshot() {
+/** Snapshot for diagnostics. */
+export function readTrackingSnapshot(sessionId) {
+    const state = stateFor(sessionId);
     return {
         features: [...state.features.keys()],
         phases: [...state.phases.keys()],