@sentropic/h2a-runtime 0.98.7-rc.1 → 0.98.7-rc.2

package/dist/vendor/engram-live/integration.d.ts

@@ -1,5 +1,6 @@
-// Vendored types for the sibling .js — see its provenance header; do not hand-edit.
-import { type CapabilityId, type CapabilityStatus, type CoverageReport, type FactBatchDto, type GrammarCoverageDto, type ValidationResult, type WorkspaceDeclarationDto } from "./contracts.js";
+// Vendored from rhanka/engram@545a57b8911ab108e84fa1778e0f268fe11bf1de: engram-live/integration.ts.
+// Compiled with TypeScript 5.9.3 (ES2022/NodeNext, declarations); do not hand-edit.
+import { type CapabilityId, type CapabilityStatus, type CoverageReport, type FactBatchDto, type GrammarCoverageDto, type LiveScope, type ValidationResult, type WorkspaceDeclarationDto } from "./contracts.js";
 export interface GitPort {
     /** Bounded Git read seam; operations arrive with L2a/L2b. Unused in L1b. */
     readonly liveGitSeam: "host-git";
@@ -18,11 +19,51 @@ export interface ContentPort {
 }
 export interface FactSinkPort {
     /** Durable receipt of a fact batch; separate from publication (spec §3). */
-    deliver(batch: FactBatchDto): Promise<{
+    deliver(batch: FactBatchDto, fencingToken: ScopeFencingTokenDto): Promise<{
         received: true;
         batchId: string;
+        receiptId?: string;
     }>;
 }
+/**
+ * Mandatory scope fencing token threaded from E (L6b) across every write,
+ * cursor, and publication port to S (L3a/L3b-S) (Opus Amendment 2).
+ */
+export interface ScopeFencingTokenDto {
+    readonly tokenId: string;
+    readonly scope: LiveScope;
+    readonly epoch: number;
+    readonly epochId: string;
+    readonly declarationRevision: number;
+    readonly projectionIncarnation: string;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+}
+/**
+ * Required S-side storage contract for L3a / L3b-S (Opus Amendment 2):
+ * Every storage write, cursor update, and generation publication MUST atomically
+ * verify the caller's ScopeFencingTokenDto against the active writer lease and
+ * storage-owned projection incarnation P inside the storage transaction.
+ */
+export interface StorageIncarnationPort {
+    incarnation(): string;
+    hasGeneration(incarnation: string, generationId: string): boolean;
+    validateFencingToken(token: ScopeFencingTokenDto, nowMs: number): ValidationResult;
+}
+export declare const REQUIRED_STORAGE_FENCING_CONTRACT: {
+    readonly enforcedByLots: readonly ["L3a", "L3b-S"];
+    readonly requireAtomicLeaseCheckOnFactWrite: true;
+    readonly requireAtomicLeaseCheckOnCursorWrite: true;
+    readonly requireAtomicLeaseCheckOnGenerationPublish: true;
+    readonly requireStorageOwnedIncarnationBinding: true;
+    readonly requireAtomicLeaseCheckOnProgressReadWrite: true;
+    readonly requireAtomicLeaseCheckOnPark: true;
+    readonly requireAtomicLeaseCheckOnRelationRepair: true;
+    readonly requireAtomicLeaseCheckOnMarkerDelete: true;
+    readonly requireSourceAndProjectionEqualityOnGenerationPublish: true;
+    readonly requireSynchronousLeaseRevocationOnShutdown: true;
+};
+export declare function validateScopeFencingToken(candidate: unknown, expectedScope?: LiveScope, expectedIncarnation?: string, nowMs?: number): ValidationResult;
 export interface CachePort {
     /** Bounded, versioned cache seam; wired by L2b/L5. Unused in L1b. */
     readonly liveCacheSeam: "host-cache";
@@ -70,4 +111,3 @@ export declare function createLiveFactory(options: CreateLiveFactoryOptions): Li
 /** The advertised grammar matrix of this build, from the pinned manifest data. */
 export declare const ADVERTISED_GRAMMAR_LANGUAGES: readonly string[];
 export { deriveCloneIdentity, deriveWorktreeIdentity, deriveDeclarationIdentity, type DeclarationIdentityDto, type DeriveCloneIdentityInput, type DeriveWorktreeIdentityInput, type DeriveDeclarationIdentityInput, } from "./registration.js";
-//# sourceMappingURL=integration.d.ts.map

package/dist/vendor/engram-live/integration.js

@@ -1,8 +1,5 @@
-// Vendored from @sentropic/engram-live 0.1.0 dist/integration.js — same
-// provenance as the sibling contracts.js header (graphify@70ebdfee, pinned
-// tarball sha512 in the GUARD test). Only the derive* re-exports are
-// consumed by H; the factory reads grammars lazily through injected ports.
-// Portable: node: builtins plus siblings only. Do not hand-edit.
+// Vendored from rhanka/engram@545a57b8911ab108e84fa1778e0f268fe11bf1de: engram-live/integration.ts.
+// Compiled with TypeScript 5.9.3 (ES2022/NodeNext, declarations); do not hand-edit.
 // @sentropic/engram-live/integration — executable neutral factory
 // (spec/SPEC_LIVE_GIT_INDEXING.md §2–3, §11; plan/09 L1b).
 //
@@ -20,6 +17,69 @@ import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ADVERTISED_LANGUAGES, CAPABILITY_IDS, CAPABILITY_PLANNED_LOTS, GRAMMAR_UNAVAILABLE_REASON, NOT_IMPLEMENTED_REASON, validateFactBatch, validateWorkspaceDeclaration, } from "./contracts.js";
+export const REQUIRED_STORAGE_FENCING_CONTRACT = {
+    enforcedByLots: ["L3a", "L3b-S"],
+    requireAtomicLeaseCheckOnFactWrite: true,
+    requireAtomicLeaseCheckOnCursorWrite: true,
+    requireAtomicLeaseCheckOnGenerationPublish: true,
+    requireStorageOwnedIncarnationBinding: true,
+    requireAtomicLeaseCheckOnProgressReadWrite: true,
+    requireAtomicLeaseCheckOnPark: true,
+    requireAtomicLeaseCheckOnRelationRepair: true,
+    requireAtomicLeaseCheckOnMarkerDelete: true,
+    requireSourceAndProjectionEqualityOnGenerationPublish: true,
+    requireSynchronousLeaseRevocationOnShutdown: true,
+};
+export function validateScopeFencingToken(candidate, expectedScope, expectedIncarnation, nowMs) {
+    const errors = [];
+    if (typeof candidate !== "object" || candidate === null) {
+        return { ok: false, errors: ["fencing token must be a non-null object"] };
+    }
+    const t = candidate;
+    if (!t.scope || typeof t.scope.tenant !== "string" || typeof t.scope.clone !== "string" || typeof t.scope.worktree !== "string")
+        errors.push("fencing token requires a complete scope");
+    if (!Number.isSafeInteger(t.declarationRevision) || (t.declarationRevision ?? 0) < 1)
+        errors.push("fencing token requires declaration revision");
+    if (typeof t.epochId !== "string" || !t.epochId)
+        errors.push("fencing token requires epoch identity");
+    for (const value of [t.tokenId, t.epochId, t.projectionIncarnation, t.scope?.tenant, t.scope?.clone, t.scope?.worktree])
+        if (typeof value !== "string" || value.length < 1 || value.length > 1024)
+            errors.push("fencing identity must be bounded");
+    if (typeof t.tokenId !== "string" || t.tokenId.length === 0) {
+        errors.push("fencing token requires a non-empty tokenId");
+    }
+    if (typeof t.epoch !== "number" || !Number.isSafeInteger(t.epoch) || t.epoch < 1) {
+        errors.push("fencing token requires a positive integer epoch");
+    }
+    if (typeof t.projectionIncarnation !== "string" || t.projectionIncarnation.length === 0) {
+        errors.push("fencing token requires a non-empty projectionIncarnation");
+    }
+    if (typeof t.issuedAt !== "number" ||
+        typeof t.expiresAt !== "number" ||
+        !Number.isFinite(t.issuedAt) ||
+        !Number.isFinite(t.expiresAt) ||
+        t.expiresAt <= t.issuedAt) {
+        errors.push("fencing token requires finite issuedAt < expiresAt");
+    }
+    if (expectedScope !== undefined && t.scope !== undefined) {
+        if (t.scope.tenant !== expectedScope.tenant ||
+            t.scope.clone !== expectedScope.clone ||
+            t.scope.worktree !== expectedScope.worktree) {
+            errors.push("fencing token scope does not match target scope");
+        }
+    }
+    if (expectedIncarnation !== undefined &&
+        t.projectionIncarnation !== undefined &&
+        t.projectionIncarnation !== expectedIncarnation) {
+        errors.push("fencing token projectionIncarnation does not match active storage incarnation P");
+    }
+    if (nowMs !== undefined && typeof t.expiresAt === "number" && nowMs >= t.expiresAt) {
+        errors.push("fencing token is expired");
+    }
+    if (nowMs !== undefined && typeof t.issuedAt === "number" && t.issuedAt > nowMs)
+        errors.push("fencing token is not yet valid");
+    return { ok: errors.length === 0, errors };
+}
 function decodeJson(bytes) {
     return JSON.parse(new TextDecoder().decode(bytes));
 }

package/dist/vendor/engram-live/pr-sync.d.ts

@@ -0,0 +1,144 @@
+import { type GithubRepositoryDto, type PrCoverageDto, type PrObjectJobDto, type PrPageDto, type PrSyncCursorDto, type PrSyncErrorKind, type PullRequestFactDto } from "./contracts.js";
+/** Neutral PR sync extractor version (checkpoints are per version). */
+export declare const PR_SYNC_EXTRACTOR_VERSION = "engram-live/pr-sync/1";
+/**
+ * Overlap re-ask on incremental retries (milliseconds): the resume window
+ * re-reads recently updated PRs so a page that moved during enumeration is
+ * deduplicated instead of lost. Pure constant, consumed by hosts.
+ */
+export declare const PR_SYNC_OVERLAP_MS: number;
+export declare class PrSyncError extends Error {
+    readonly kind: PrSyncErrorKind;
+    constructor(kind: PrSyncErrorKind, message: string);
+}
+export interface PrPageRequest {
+    readonly repository: GithubRepositoryDto;
+    readonly cursor: string | null;
+    readonly updatedAtSince: number | null;
+    /**
+     * Conditional validator bound to this exact (repository, filter, cursor)
+     * position: the engine replays only the ETag stored for the requested
+     * position, never another page's validator. Null means no validator yet.
+     */
+    readonly etag: string | null;
+}
+export type PrTransportResult = {
+    readonly ok: true;
+    readonly page: PrPageDto;
+} | {
+    readonly ok: false;
+    readonly kind: PrSyncErrorKind;
+    readonly message: string;
+    readonly retryAfterMs?: number;
+};
+/**
+ * INJECTED GitHub listing transport (neutral port). Production H: serves it
+ * with the approved installed `gh` binary, host-controlled credentials and
+ * ETag/rate-limit handling; tests serve fixture pages. No network in engram.
+ * The request carries no count limit: the engine never sends a ceiling.
+ */
+export interface GithubPrTransportPort {
+    fetchPage(request: PrPageRequest): Promise<PrTransportResult>;
+}
+/**
+ * INJECTED durable PR persistence (neutral port, never a base). Engram owns
+ * no database; cluster-mesh/app implement it behind this shape (S mapping).
+ * Retention contract: saveObservation keeps every distinct observation —
+ * a moved head, a state change, a base change or new merge evidence appends
+ * a row, never erases the previous one; only byte-identical repeats
+ * collapse. Object jobs are keyed by (repository, PR, head OID): recording
+ * head B never replaces head A's job, its failures or its receipts.
+ */
+export interface PrSyncPersistencePort {
+    loadCursor(repository: GithubRepositoryDto): Promise<PrSyncCursorDto | null>;
+    saveCursor(cursor: PrSyncCursorDto): Promise<void>;
+    saveObservation(fact: PullRequestFactDto): Promise<void>;
+    listObservations(repository: GithubRepositoryDto): Promise<readonly PullRequestFactDto[]>;
+    recordObjectJob(job: PrObjectJobDto): Promise<void>;
+    updateObjectJob(job: PrObjectJobDto): Promise<void>;
+    listObjectJobs(repository: GithubRepositoryDto): Promise<readonly PrObjectJobDto[]>;
+}
+export interface PrSyncInput {
+    readonly repository: GithubRepositoryDto;
+    readonly sweepKind: "incremental" | "full";
+    readonly now: number;
+}
+export interface PrSyncStats {
+    readonly pages: number;
+    readonly itemsSeen: number;
+    readonly unique: number;
+    readonly duplicates: number;
+    readonly observations: number;
+    readonly objectJobsPending: number;
+}
+export interface PrSyncOutcome {
+    readonly state: "complete" | "stale";
+    readonly observations: readonly PullRequestFactDto[];
+    readonly cursor: PrSyncCursorDto;
+    readonly coverage: readonly PrCoverageDto[];
+    readonly stats: PrSyncStats;
+}
+/**
+ * Identity of one persisted observation: the complete observed fact. Two
+ * rows sharing one head OID but differing by state, draft flag, refs, base,
+ * merge evidence or timestamp are different observations and all persist;
+ * only a byte-identical repeat collapses. The (PR, head OID) key is reserved
+ * for object-job deduplication (objectJobIdentityKey), never for dropping
+ * observations.
+ */
+export declare function observationIdentityKey(fact: PullRequestFactDto): string;
+/**
+ * Identity of one object-acquisition job: the PR plus the observed head OID.
+ * Two jobs for one PR with different heads are different rows; recording
+ * head B never replaces head A's job, failures or receipts.
+ */
+export declare function objectJobIdentityKey(job: Pick<PrObjectJobDto, "repositoryOwner" | "repositoryRepo" | "prNumber" | "headOid">): string;
+/**
+ * Deduplicate exact observation repeats by complete observation identity,
+ * keeping one row per distinct fact. Observations whose metadata differs
+ * (state, base, merge evidence, timestamp, …) are all kept: this is the
+ * persistence rule (nothing erased), not the current view.
+ */
+export declare function deduplicatePrObservations(items: readonly PullRequestFactDto[]): readonly PullRequestFactDto[];
+/**
+ * Current view over observations: one row per PR identity
+ * (owner/repo/number), keeping the newest updatedAt record. Computed
+ * separately AFTER every distinct observation is retained, so the live head
+ * never erases the observed history.
+ */
+export declare function deduplicatePrPageItems(items: readonly PullRequestFactDto[]): readonly PullRequestFactDto[];
+/**
+ * Refuse any row that does not belong to the requested repository: the
+ * stored cursor and every received observation must carry the canonical
+ * requested identity before any persistence or completion. A foreign row is
+ * a protocol failure, never a silent adoption.
+ */
+export declare function assertSameRepository(expected: GithubRepositoryDto, owner: string, repo: string, what: string): void;
+/**
+ * ETag position key: one validator per (filter, cursor) position inside the
+ * repository pass, so page N's ETag is never replayed for page M.
+ */
+export declare function etagPositionKey(cursor: string | null, updatedAtSince: number | null): string;
+/**
+ * Require the explicit end-of-list proof: hasMore false without endProof is
+ * a protocol failure, never a silent completion. hasMore true without a
+ * continuation cursor is the same failure class.
+ */
+export declare function requireEndOfListProof(page: PrPageDto): void;
+/**
+ * S mapping rule: metadata receipts never acknowledge a failed private
+ * object acquisition. True only when every job is acquired AND verified:
+ * the acquired OID equals the observed head OID, no residual error stands,
+ * and known counters agree exactly (a partial count never acknowledges).
+ */
+export declare function canAcknowledgePrObjects(jobs: readonly PrObjectJobDto[]): boolean;
+/**
+ * Run one neutral PR sync pass: full pagination with overlap/dedup, durable
+ * cursor advance only after proven completion, object jobs recorded as
+ * pending independently of metadata, failures preserving last success with
+ * stale coverage and durable retry state for automatic resume.
+ */
+export declare function runPrSyncPass(input: PrSyncInput, ports: {
+    readonly transport: GithubPrTransportPort;
+    readonly persistence: PrSyncPersistencePort;
+}): Promise<PrSyncOutcome>;