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

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

@@ -0,0 +1,113 @@
+// 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";
+}
+export interface FilesystemPort {
+    /** Reads a file's bytes through the injected host filesystem. */
+    readFileBytes(path: string): Promise<Uint8Array>;
+}
+export interface ClockPort {
+    /** Milliseconds since the Unix epoch, host-supplied and test-fakeable. */
+    now(): number;
+}
+export interface ContentPort {
+    /** Content classification seam; policies arrive with L4b/L5. Unused in L1b. */
+    readonly liveContentSeam: "host-content";
+}
+export interface FactSinkPort {
+    /** Durable receipt of a fact batch; separate from publication (spec §3). */
+    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";
+}
+export interface GrammarRuntimePort {
+    /** Loads a tree-sitter WASM grammar from bytes (e.g. web-tree-sitter). */
+    loadLanguage(wasm: Uint8Array): Promise<unknown>;
+}
+export interface LiveFactoryPorts {
+    readonly git: GitPort;
+    readonly filesystem: FilesystemPort;
+    readonly clock: ClockPort;
+    readonly content: ContentPort;
+    readonly factSink: FactSinkPort;
+    readonly cache: CachePort;
+    readonly grammarRuntime: GrammarRuntimePort;
+}
+export interface CreateLiveFactoryOptions {
+    readonly ports: LiveFactoryPorts;
+    readonly declaration: WorkspaceDeclarationDto;
+}
+export interface CapabilityResult {
+    readonly capability: CapabilityId;
+    readonly state: "unavailable";
+    readonly reason: string;
+    readonly plannedLot: string;
+    readonly delivered: false;
+}
+export interface GrammarLoadResult {
+    readonly language: string;
+    readonly state: "available" | "unavailable";
+    readonly bytesSha256?: string;
+    readonly grammar?: unknown;
+    readonly reason?: string;
+}
+export interface LiveFactory {
+    describeCapabilities(): readonly CapabilityStatus[];
+    runCapability(capability: CapabilityId): Promise<CapabilityResult>;
+    grammarCoverage(language: string): GrammarCoverageDto;
+    grammarCoverageReport(language: string): CoverageReport;
+    loadGrammar(language: string): Promise<GrammarLoadResult>;
+    validateBatch(batch: unknown): ValidationResult;
+}
+export declare function createLiveFactory(options: CreateLiveFactoryOptions): LiveFactory;
+/** 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";

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

@@ -0,0 +1,254 @@
+// 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).
+//
+// The factory composes injected capabilities only: Git, filesystem, clock,
+// content, fact-sink, cache and grammar ports. It never imports the
+// monolithic root CLI, another @sentropic/* consumer package, the h2a host,
+// a model module or a storage-driver handle — those stay outside the neutral
+// closure by construction and by tests/live-neutrality.test.ts.
+//
+// L1b supplies the package/factory seams and grammar loading. Every other
+// capability is explicitly unavailable until its lot lands; the factory
+// never fabricates facts, writes through the fact sink or silently
+// degrades an unavailable capability into an empty success.
+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));
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// The pinned manifest is validated before any grammar is trusted: a
+// manifestVersion number and a languages record whose entries pin a
+// non-empty file and sha256 are required.
+function isGrammarManifest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.manifestVersion !== "number")
+        return false;
+    if (typeof candidate.languages !== "object" || candidate.languages === null || Array.isArray(candidate.languages)) {
+        return false;
+    }
+    return Object.values(candidate.languages).every((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return false;
+        const record = entry;
+        return typeof record.file === "string" && record.file.length > 0
+            && typeof record.sha256 === "string" && record.sha256.length > 0;
+    });
+}
+export function createLiveFactory(options) {
+    const declarationCheck = validateWorkspaceDeclaration(options.declaration);
+    if (!declarationCheck.ok) {
+        throw new Error(`invalid live workspace declaration: ${declarationCheck.errors.join("; ")}`);
+    }
+    const ports = options.ports;
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    const manifestPath = join(distDir, "..", "grammar-manifest.json");
+    const grammarDir = join(distDir, "grammars");
+    let manifestCache;
+    const loadManifest = async () => {
+        if (manifestCache)
+            return { ok: true, manifest: manifestCache };
+        let decoded;
+        try {
+            decoded = decodeJson(await ports.filesystem.readFileBytes(manifestPath));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: `the pinned grammar manifest cannot be read through the filesystem port (${errorMessage(error)})`,
+            };
+        }
+        if (!isGrammarManifest(decoded)) {
+            return {
+                ok: false,
+                reason: "the pinned grammar manifest is invalid: a manifestVersion number and a languages record pinning file/sha256 entries are required",
+            };
+        }
+        manifestCache = decoded;
+        return { ok: true, manifest: decoded };
+    };
+    const grammarLoadCache = new Map();
+    return {
+        describeCapabilities() {
+            return CAPABILITY_IDS.map((capability) => ({
+                capability,
+                state: "unavailable",
+                reason: NOT_IMPLEMENTED_REASON,
+                plannedLot: CAPABILITY_PLANNED_LOTS[capability],
+            }));
+        },
+        async runCapability(capability) {
+            if (!CAPABILITY_IDS.includes(capability)) {
+                throw new Error(`unknown capability "${String(capability)}"; known capabilities: ${CAPABILITY_IDS.join(", ")}`);
+            }
+            // Explicit unavailability: no port call, no fabricated facts, no
+            // empty-success degradation.
+            return {
+                capability,
+                state: "unavailable",
+                reason: NOT_IMPLEMENTED_REASON,
+                plannedLot: CAPABILITY_PLANNED_LOTS[capability],
+                delivered: false,
+            };
+        },
+        grammarCoverage(language) {
+            // Synchronous coverage uses the pinned manifest; loadGrammar caches the
+            // executed result per language so coverage reflects verified assets.
+            const loaded = grammarLoadCache.get(language);
+            if (loaded?.state === "available") {
+                return { axis: "ast", language, state: "current", reason: `packaged grammar verified (sha256 ${loaded.bytesSha256})` };
+            }
+            return {
+                axis: "ast",
+                language,
+                state: "unavailable",
+                reason: `${GRAMMAR_UNAVAILABLE_REASON}: "${language}" has no verified packaged grammar in this session`,
+            };
+        },
+        grammarCoverageReport(language) {
+            const coverage = this.grammarCoverage(language);
+            return {
+                axis: coverage.axis,
+                language,
+                state: coverage.state,
+                reason: coverage.reason,
+                checkedAt: ports.clock.now(),
+            };
+        },
+        async loadGrammar(language) {
+            const cached = grammarLoadCache.get(language);
+            if (cached)
+                return cached;
+            const unavailable = (reason) => {
+                const result = { language, state: "unavailable", reason };
+                grammarLoadCache.set(language, result);
+                return result;
+            };
+            // Reading and validating the manifest is part of the load: an absent,
+            // unreadable or invalid manifest yields an explicit unavailable result,
+            // never a thrown error and never a silent empty success.
+            const manifestOutcome = await loadManifest();
+            if (!manifestOutcome.ok || manifestOutcome.manifest === undefined) {
+                return unavailable(`${GRAMMAR_UNAVAILABLE_REASON}: ${manifestOutcome.reason ?? "the pinned grammar manifest is unavailable"}`);
+            }
+            // Clean own-property lookup: inherited names such as "constructor" or
+            // "toString" never reach a manifest entry.
+            if (!Object.hasOwn(manifestOutcome.manifest.languages, language)) {
+                return unavailable(`${GRAMMAR_UNAVAILABLE_REASON}: "${language}" is absent from the pinned grammar manifest`);
+            }
+            const entry = manifestOutcome.manifest.languages[language];
+            let bytes;
+            try {
+                bytes = await ports.filesystem.readFileBytes(join(grammarDir, entry.file));
+            }
+            catch (error) {
+                return unavailable(`${GRAMMAR_UNAVAILABLE_REASON}: the packaged WASM for "${language}" cannot be read through the filesystem port (${errorMessage(error)})`);
+            }
+            const digest = sha256(bytes);
+            if (digest !== entry.sha256) {
+                return unavailable(`packaged grammar digest mismatch for "${language}": pinned ${entry.sha256}, read ${digest}`);
+            }
+            try {
+                const grammar = await ports.grammarRuntime.loadLanguage(bytes);
+                const result = {
+                    language,
+                    state: "available",
+                    bytesSha256: digest,
+                    grammar,
+                };
+                grammarLoadCache.set(language, result);
+                return result;
+            }
+            catch (error) {
+                return unavailable(`grammar runtime rejected the packaged WASM for "${language}": ${errorMessage(error)}`);
+            }
+        },
+        validateBatch(batch) {
+            return validateFactBatch(batch);
+        },
+    };
+}
+/** The advertised grammar matrix of this build, from the pinned manifest data. */
+export const ADVERTISED_GRAMMAR_LANGUAGES = ADVERTISED_LANGUAGES;
+// The canonical identity derivation (L6a, spec §3/§12) is part of the public
+// integration surface: h2a and cluster-mesh mint cloneId/worktreeId/
+// declarationId through exactly these functions, so every seat derives
+// byte-identical opaque ids from identical components. The minting needs
+// node:crypto (sha256), which keeps it out of the data-pure /contracts
+// entry; the derivation itself stays pure and deterministic over its
+// arguments (see ./registration.js).
+export { deriveCloneIdentity, deriveWorktreeIdentity, deriveDeclarationIdentity, } from "./registration.js";

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>;