@aiwg/cli 2026.10.10 → 2026.10.12

package/dist/src/storage/migration-protocol.js

@@ -1,21 +1,20 @@
-import { createHash, randomUUID } from 'node:crypto';
-export const STORAGE_MIGRATION_PROTOCOL = 'aiwg.storage-migration/v1';
-export class MigrationProtocolError extends Error {
-    code;
-    retryable;
-    constructor(code, message, retryable = false) {
-        super(message);
-        this.code = code;
-        this.retryable = retryable;
-        this.name = 'MigrationProtocolError';
-    }
-}
+// Coordinates protocol migration, copy checkpoints and backend cutover.
+import { randomUUID } from 'node:crypto';
+import { MigrationProtocolError, STORAGE_MIGRATION_PROTOCOL, } from './migration-types.js';
+import { boundedInteger, digestRecords, assertBoundaryState, validateManifest, summarizeVerificationFailure, sha256, stableStringify, approvalDigest, recordMap, digestRecordChunks, validateSemanticVerification, semanticIsValid, receiptKey, identityKey, recordKey, compareRevisions, revisionConflict, chunk, commitMigrationRecords, isRetryableError, errorMessage, abortableDelay, } from './migration-records.js';
+import { runMigrationCopy } from './migration-copy.js';
+export * from './migration-types.js';
+export { digestRecords, digestRecordChunks, approvalDigest, validateManifest } from './migration-records.js';
 export class StorageMigrationCoordinator {
     source;
     destination;
     store;
     routing;
     options;
+    /** Copy-only CLI workflow: digest-aware resume and plan-authorized deletes, without cutover. */
+    static copy(request) {
+        return runMigrationCopy(request);
+    }
     batchSize;
     concurrency;
     maxRetries;
@@ -303,33 +302,11 @@ export class StorageMigrationCoordinator {
                 if (index >= batches.length)
                     return;
                 const batch = batches[index];
-                const mutations = batch.map(record => mutationFor(manifest.migrationId, record, latest.get(identityKey(record.identity))?.destinationRevision));
-                const receipt = await this.retry(() => this.destination.commitBatch(mutations, this.options.signal), `batch ${index}`);
-                if (!receipt.committed || receipt.recordReceipts.length !== batch.length) {
-                    throw new MigrationProtocolError('AIWG_MIGRATION_INVALID_RECEIPT', `destination returned an invalid receipt for batch ${index}`);
-                }
-                const committedAt = this.now().toISOString();
-                const committedByIdentity = new Map(receipt.recordReceipts.map(recordReceipt => [identityKey(recordReceipt.identity), recordReceipt]));
-                for (let recordIndex = 0; recordIndex < batch.length; recordIndex++) {
-                    const record = batch[recordIndex];
-                    const committed = committedByIdentity.get(identityKey(record.identity));
-                    if (!committed || committed.digest !== record.digest) {
-                        throw new MigrationProtocolError('AIWG_MIGRATION_CORRUPT_RECEIPT', `destination receipt diverged for ${identityKey(record.identity)}`);
-                    }
-                    manifest.records.push({
-                        identity: record.identity,
-                        sourceRevision: record.sourceRevision,
-                        contentDigest: record.digest,
-                        destinationRevision: committed.sourceRevision,
-                        tombstone: Boolean(record.tombstone),
-                        idempotencyKey: mutations[recordIndex].idempotencyKey,
-                        batchId: receipt.batchId,
-                        committedAt,
-                    });
-                }
+                const committed = await commitMigrationRecords(manifest.migrationId, batch, record => latest.get(identityKey(record.identity))?.destinationRevision, mutations => this.retry(() => this.destination.commitBatch(mutations, this.options.signal), `batch ${index}`), this.now);
+                manifest.records.push(...committed.records);
                 manifest.counts.committed = manifest.records.length;
                 manifest.checkpoint.committedBatches += 1;
-                manifest.checkpoint.highWaterMark = receipt.highWaterMark;
+                manifest.checkpoint.highWaterMark = committed.batch.highWaterMark;
                 await this.persist(manifest);
             }
         });
@@ -393,164 +370,4 @@ export class StorageMigrationCoordinator {
         }
     }
 }
-export function digestRecords(records) {
-    const normalized = [...records]
-        .map(record => ({
-        identity: record.identity,
-        sourceRevision: record.sourceRevision,
-        digest: record.digest,
-        tombstone: record.tombstone ?? null,
-    }))
-        .sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
-    return sha256(stableStringify(normalized));
-}
-export function digestRecordChunks(records, chunkSize) {
-    const sorted = [...records].sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
-    return chunk(sorted, chunkSize).map(recordsInChunk => digestRecords(recordsInChunk));
-}
-export function approvalDigest(manifest) {
-    const copy = structuredClone(manifest);
-    delete copy.digests.approval;
-    return sha256(stableStringify(copy));
-}
-export function validateManifest(manifest, source, destination) {
-    if (manifest.protocol !== STORAGE_MIGRATION_PROTOCOL) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_PROTOCOL_UNSUPPORTED', `unsupported migration protocol ${String(manifest.protocol)}`);
-    }
-    if (!manifest.migrationId || !manifest.snapshot?.id || !manifest.digests?.source) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_MANIFEST_CORRUPT', 'migration manifest is missing required identity or digest fields');
-    }
-    if (!manifest.boundaries?.initial) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_MISSING', 'migration manifest has no durable source boundary receipt');
-    }
-    assertBoundaryState(manifest.boundaries.initial, manifest.mode === 'offline' ? 'quiesced' : 'tracking', 'initial');
-    if (source && stableStringify(manifest.source) !== stableStringify(source)) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_SOURCE_MISMATCH', 'manifest source does not match the active source');
-    }
-    if (destination && stableStringify(manifest.destination) !== stableStringify(destination)) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_DESTINATION_MISMATCH', 'manifest destination does not match the active destination');
-    }
-}
-function assertBoundaryState(boundary, expected, stage) {
-    if (!boundary.boundaryId || !boundary.establishedAt || boundary.state !== expected) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_INVALID', `${stage} source boundary must provide a durable ${expected} receipt`);
-    }
-}
-function mutationFor(migrationId, record, expectedRevision) {
-    return {
-        operation: record.tombstone ? 'delete' : 'upsert',
-        record,
-        idempotencyKey: sha256(`${migrationId}\0${recordKey(record)}`),
-        ...(expectedRevision === undefined ? {} : { expectedRevision }),
-    };
-}
-function revisionConflict(identity, revision) {
-    return new MigrationProtocolError('AIWG_MIGRATION_REVISION_CONFLICT', `source revision ${revision} has conflicting content for ${identity}`);
-}
-function compareRevisions(comparator, left, right) {
-    const result = comparator(left, right);
-    if (!Number.isFinite(result)) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_REVISION_ORDER_INVALID', 'source-revision comparator returned a non-finite result');
-    }
-    return Math.sign(result);
-}
-function recordMap(records) {
-    return new Map(records.map(record => [identityKey(record.identity), record]));
-}
-function identityKey(identity) {
-    return `${identity.tenant}\0${identity.subsystem}\0${identity.path}`;
-}
-function recordKey(record) {
-    return `${identityKey(record.identity)}\0${record.sourceRevision}\0${record.digest}`;
-}
-function receiptKey(receipt) {
-    return `${identityKey(receipt.identity)}\0${receipt.sourceRevision}\0${receipt.contentDigest}`;
-}
-function sha256(value) {
-    return createHash('sha256').update(value).digest('hex');
-}
-function stableStringify(value) {
-    if (Array.isArray(value))
-        return `[${value.map(stableStringify).join(',')}]`;
-    if (value && typeof value === 'object') {
-        return `{${Object.entries(value)
-            .filter(([, child]) => child !== undefined)
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`)
-            .join(',')}}`;
-    }
-    return JSON.stringify(value);
-}
-function chunk(items, size) {
-    const chunks = [];
-    for (let index = 0; index < items.length; index += size)
-        chunks.push(items.slice(index, index + size));
-    return chunks;
-}
-function boundedInteger(raw, fallback, min, max, label) {
-    const value = raw ?? fallback;
-    if (!Number.isInteger(value) || value < min || value > max) {
-        throw new MigrationProtocolError('AIWG_MIGRATION_INVALID_OPTION', `${label} must be an integer from ${min} through ${max}`);
-    }
-    return value;
-}
-function summarizeVerificationFailure(verification) {
-    const semanticFailures = Object.values(verification.semantic).filter(check => !check.valid).length;
-    return `migration parity failed: missing=${verification.missing.length} unexpected=${verification.unexpected.length} corrupt=${verification.corrupt.length} chunks=${verification.chunks.valid ? 'valid' : 'invalid'} semantic=${semanticFailures} lag=${verification.lag}`;
-}
-function validateSemanticVerification(verification) {
-    for (const dimension of [
-        'schema', 'constraints', 'countsByType', 'edgeIntegrity', 'queryParity', 'traversalParity',
-    ]) {
-        const check = verification?.[dimension];
-        if (!check || typeof check.valid !== 'boolean' || !Number.isInteger(check.declared) || check.declared < 0 ||
-            !Number.isInteger(check.checked) || check.checked < 0 || check.checked !== check.declared || !Array.isArray(check.failures)) {
-            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification is incomplete for ${dimension}`);
-        }
-        if (check.valid !== (check.failures.length === 0)) {
-            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification validity disagrees with failures for ${dimension}`);
-        }
-        if (check.evidenceDigest !== undefined && !/^[0-9A-Za-z._:-]+$/.test(check.evidenceDigest)) {
-            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification evidence digest is invalid for ${dimension}`);
-        }
-        if (['schema', 'constraints', 'queryParity'].includes(dimension) && check.declared < 1) {
-            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification must exercise at least one ${dimension} check`);
-        }
-        if (dimension === 'countsByType') {
-            if (!isCountMap(check.sourceCounts) || !isCountMap(check.destinationCounts)) {
-                throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', 'countsByType must include non-negative integer source and destination maps');
-            }
-            const declaredTypes = new Set([...Object.keys(check.sourceCounts), ...Object.keys(check.destinationCounts)]).size;
-            if (check.declared !== declaredTypes || (check.valid && stableStringify(check.sourceCounts) !== stableStringify(check.destinationCounts))) {
-                throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', 'countsByType scope or validity does not match its declared maps');
-            }
-        }
-    }
-}
-function semanticIsValid(verification) {
-    return Object.values(verification).every(check => check.valid);
-}
-function isCountMap(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value) &&
-        Object.values(value).every(count => Number.isInteger(count) && count >= 0);
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function isRetryableError(error) {
-    return typeof error === 'object' && error !== null && 'retryable' in error && error.retryable === true;
-}
-async function abortableDelay(ms, signal) {
-    if (!signal) {
-        await new Promise(resolve => setTimeout(resolve, ms));
-        return;
-    }
-    await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, ms);
-        signal.addEventListener('abort', () => {
-            clearTimeout(timer);
-            reject(new MigrationProtocolError('AIWG_MIGRATION_CANCELLED', 'migration cancelled by operator'));
-        }, { once: true });
-    });
-}
 //# sourceMappingURL=migration-protocol.js.map

package/dist/src/storage/migration-records.js

@@ -0,0 +1,186 @@
+// Record digests, validation and retry helpers for storage migration.
+import { createHash } from 'node:crypto';
+import { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, } from './migration-types.js';
+export function digestRecords(records) {
+    const normalized = [...records]
+        .map(record => ({
+        identity: record.identity,
+        sourceRevision: record.sourceRevision,
+        digest: record.digest,
+        tombstone: record.tombstone ?? null,
+    }))
+        .sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
+    return sha256(stableStringify(normalized));
+}
+export function digestRecordChunks(records, chunkSize) {
+    const sorted = [...records].sort((left, right) => identityKey(left.identity).localeCompare(identityKey(right.identity)));
+    return chunk(sorted, chunkSize).map(recordsInChunk => digestRecords(recordsInChunk));
+}
+export function approvalDigest(manifest) {
+    const copy = structuredClone(manifest);
+    delete copy.digests.approval;
+    return sha256(stableStringify(copy));
+}
+export function validateManifest(manifest, source, destination) {
+    if (manifest.protocol !== STORAGE_MIGRATION_PROTOCOL) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_PROTOCOL_UNSUPPORTED', `unsupported migration protocol ${String(manifest.protocol)}`);
+    }
+    if (!manifest.migrationId || !manifest.snapshot?.id || !manifest.digests?.source) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_MANIFEST_CORRUPT', 'migration manifest is missing required identity or digest fields');
+    }
+    if (!manifest.boundaries?.initial) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_MISSING', 'migration manifest has no durable source boundary receipt');
+    }
+    assertBoundaryState(manifest.boundaries.initial, manifest.mode === 'offline' ? 'quiesced' : 'tracking', 'initial');
+    if (source && stableStringify(manifest.source) !== stableStringify(source)) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_SOURCE_MISMATCH', 'manifest source does not match the active source');
+    }
+    if (destination && stableStringify(manifest.destination) !== stableStringify(destination)) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_DESTINATION_MISMATCH', 'manifest destination does not match the active destination');
+    }
+}
+export function assertBoundaryState(boundary, expected, stage) {
+    if (!boundary.boundaryId || !boundary.establishedAt || boundary.state !== expected) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_BOUNDARY_INVALID', `${stage} source boundary must provide a durable ${expected} receipt`);
+    }
+}
+export function mutationFor(migrationId, record, expectedRevision) {
+    return {
+        operation: record.tombstone ? 'delete' : 'upsert',
+        record,
+        idempotencyKey: sha256(`${migrationId}\0${recordKey(record)}`),
+        ...(expectedRevision === undefined ? {} : { expectedRevision }),
+    };
+}
+export function revisionConflict(identity, revision) {
+    return new MigrationProtocolError('AIWG_MIGRATION_REVISION_CONFLICT', `source revision ${revision} has conflicting content for ${identity}`);
+}
+export function compareRevisions(comparator, left, right) {
+    const result = comparator(left, right);
+    if (!Number.isFinite(result)) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_REVISION_ORDER_INVALID', 'source-revision comparator returned a non-finite result');
+    }
+    return Math.sign(result);
+}
+export function recordMap(records) {
+    return new Map(records.map(record => [identityKey(record.identity), record]));
+}
+export function identityKey(identity) {
+    return `${identity.tenant}\0${identity.subsystem}\0${identity.path}`;
+}
+export function recordKey(record) {
+    return `${identityKey(record.identity)}\0${record.sourceRevision}\0${record.digest}`;
+}
+export function receiptKey(receipt) {
+    return `${identityKey(receipt.identity)}\0${receipt.sourceRevision}\0${receipt.contentDigest}`;
+}
+export function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function chunk(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size)
+        chunks.push(items.slice(index, index + size));
+    return chunks;
+}
+export function boundedInteger(raw, fallback, min, max, label) {
+    const value = raw ?? fallback;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_INVALID_OPTION', `${label} must be an integer from ${min} through ${max}`);
+    }
+    return value;
+}
+export function summarizeVerificationFailure(verification) {
+    const semanticFailures = Object.values(verification.semantic).filter(check => !check.valid).length;
+    return `migration parity failed: missing=${verification.missing.length} unexpected=${verification.unexpected.length} corrupt=${verification.corrupt.length} chunks=${verification.chunks.valid ? 'valid' : 'invalid'} semantic=${semanticFailures} lag=${verification.lag}`;
+}
+export function validateSemanticVerification(verification) {
+    for (const dimension of [
+        'schema', 'constraints', 'countsByType', 'edgeIntegrity', 'queryParity', 'traversalParity',
+    ]) {
+        const check = verification?.[dimension];
+        if (!check || typeof check.valid !== 'boolean' || !Number.isInteger(check.declared) || check.declared < 0 ||
+            !Number.isInteger(check.checked) || check.checked < 0 || check.checked !== check.declared || !Array.isArray(check.failures)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification is incomplete for ${dimension}`);
+        }
+        if (check.valid !== (check.failures.length === 0)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification validity disagrees with failures for ${dimension}`);
+        }
+        if (check.evidenceDigest !== undefined && !/^[0-9A-Za-z._:-]+$/.test(check.evidenceDigest)) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification evidence digest is invalid for ${dimension}`);
+        }
+        if (['schema', 'constraints', 'queryParity'].includes(dimension) && check.declared < 1) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', `semantic verification must exercise at least one ${dimension} check`);
+        }
+        if (dimension === 'countsByType') {
+            if (!isCountMap(check.sourceCounts) || !isCountMap(check.destinationCounts)) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', 'countsByType must include non-negative integer source and destination maps');
+            }
+            const declaredTypes = new Set([...Object.keys(check.sourceCounts), ...Object.keys(check.destinationCounts)]).size;
+            if (check.declared !== declaredTypes || (check.valid && stableStringify(check.sourceCounts) !== stableStringify(check.destinationCounts))) {
+                throw new MigrationProtocolError('AIWG_MIGRATION_SEMANTIC_VERIFICATION_INVALID', 'countsByType scope or validity does not match its declared maps');
+            }
+        }
+    }
+}
+export function semanticIsValid(verification) {
+    return Object.values(verification).every(check => check.valid);
+}
+export function isCountMap(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) &&
+        Object.values(value).every(count => Number.isInteger(count) && count >= 0);
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function isRetryableError(error) {
+    return typeof error === 'object' && error !== null && 'retryable' in error && error.retryable === true;
+}
+export async function abortableDelay(ms, signal) {
+    if (!signal) {
+        await new Promise(resolve => setTimeout(resolve, ms));
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new MigrationProtocolError('AIWG_MIGRATION_CANCELLED', 'migration cancelled by operator'));
+        }, { once: true });
+    });
+}
+/** Shared batch mutation and receipt validation for copy-only and cutover migrations. */
+export async function commitMigrationRecords(migrationId, records, expectedRevision, commit, now) {
+    const mutations = records.map(record => mutationFor(migrationId, record, expectedRevision(record)));
+    const batch = await commit(mutations);
+    if (!batch.committed || batch.recordReceipts.length !== records.length) {
+        throw new MigrationProtocolError('AIWG_MIGRATION_INVALID_RECEIPT', 'destination returned an invalid batch receipt');
+    }
+    const committedByIdentity = new Map(batch.recordReceipts.map(receipt => [identityKey(receipt.identity), receipt]));
+    const committedAt = now().toISOString();
+    const receipts = records.map((record, index) => {
+        const committed = committedByIdentity.get(identityKey(record.identity));
+        if (!committed || committed.digest !== record.digest) {
+            throw new MigrationProtocolError('AIWG_MIGRATION_CORRUPT_RECEIPT', `destination receipt diverged for ${identityKey(record.identity)}`);
+        }
+        return {
+            identity: record.identity, sourceRevision: record.sourceRevision, contentDigest: record.digest,
+            destinationRevision: committed.sourceRevision, tombstone: Boolean(record.tombstone),
+            idempotencyKey: mutations[index].idempotencyKey, batchId: batch.batchId, committedAt,
+        };
+    });
+    return { batch, records: receipts };
+}
+//# sourceMappingURL=migration-records.js.map

package/dist/src/storage/migration-types.js

@@ -0,0 +1,12 @@
+export const STORAGE_MIGRATION_PROTOCOL = 'aiwg.storage-migration/v1';
+export class MigrationProtocolError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'MigrationProtocolError';
+    }
+}
+//# sourceMappingURL=migration-types.js.map

package/dist/src/tracker/forge-http.js

@@ -202,7 +202,7 @@ export function classifyStatus(response) {
         return 'server-error';
     return 'unexpected-status';
 }
-function parseJson(response) {
+export function parseForgeJson(response) {
     const failure = classifyStatus(response);
     if (failure)
         throw new ForgeReadError(failure, response.status);
@@ -213,6 +213,7 @@ function parseJson(response) {
         throw new ForgeReadError('malformed');
     }
 }
+const parseJson = parseForgeJson;
 /**
  * Pagination from the provider headers (`x-hasmore`, `link rel="next"`,
  * `x-total-count` / `x-total`). A full page with no pagination signal is

package/dist/src/tracker/issue-pages.js

@@ -0,0 +1,110 @@
+// Cursor-paged, metadata-only backlog views over the existing bounded forge transport.
+import { createForgeReader, parseForgeJson, forgePagination, ForgeReadError, } from './forge-http.js';
+import { AuditStop, auditDigest, boundedPageSize, decodeAuditCursor, encodeAuditCursor, parseAuditFilter, } from '../issues/audit-contract.js';
+export function createForgeAuditTracker(provider, repository, transport, identity = `${provider}:${repository}`) {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repository) || repository.split('/').some(p => p === '.' || p === '..')) {
+        throw new AuditStop('tracker-repository-invalid');
+    }
+    const root = `/repos/${repository.split('/').map(encodeURIComponent).join('/')}/issues`;
+    const sizeKey = provider === 'github' ? 'per_page' : 'limit';
+    const object = (raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new ForgeReadError('malformed');
+        return raw;
+    };
+    return {
+        identity,
+        async listMetadata(options) {
+            const size = boundedPageSize(options.pageSize);
+            const filter = parseAuditFilter(options.filter);
+            const scope = auditDigest([identity, size, filter]);
+            const cursor = options.cursor ? decodeAuditCursor(options.cursor) : null;
+            if (options.cursor && (!cursor || typeof cursor !== 'object'))
+                throw new AuditStop('cursor-invalidated');
+            if (cursor && (cursor.scope !== scope || !Number.isSafeInteger(cursor.page) || cursor.page < 2
+                || typeof cursor.previous !== 'string'))
+                throw new AuditStop('cursor-invalidated');
+            const read = async (page) => {
+                const query = new URLSearchParams({ state: filter.status, sort: provider === 'gitea' ? 'oldest' : 'created', direction: 'asc',
+                    page: String(page), [sizeKey]: String(size), ...(provider === 'gitea' ? { type: 'issues' } : {}) });
+                if (filter.labels.length)
+                    query.set('labels', filter.labels.join(','));
+                const response = await transport(`${root}?${query}`, options.signal);
+                if (response.body.length > options.maxBytes)
+                    throw new AuditStop('byte-budget');
+                const raw = parseForgeJson(response);
+                if (!Array.isArray(raw) || raw.length > size)
+                    throw new ForgeReadError('malformed');
+                const records = raw.map(object);
+                const items = records.filter(r => !r.pull_request).map(r => {
+                    const number = r.number ?? r.index;
+                    if (!Number.isSafeInteger(number) || Number(number) < 1 || typeof r.title !== 'string'
+                        || typeof r.updated_at !== 'string' || (r.state !== 'open' && r.state !== 'closed'))
+                        throw new ForgeReadError('malformed');
+                    return { id: String(number), title: r.title, status: r.state, updatedAt: r.updated_at,
+                        labels: Array.isArray(r.labels) ? r.labels.map(l => typeof l === 'string' ? l : String(object(l).name ?? '')) : [] };
+                });
+                // Fingerprint includes PR positions, but excludes bodies/comments discarded at this boundary.
+                const fingerprint = auditDigest(records.map(r => [r.number ?? r.index, r.updated_at, r.state, r.title, r.labels]));
+                const pagination = forgePagination(response.headers, raw, page, size);
+                return { items, fingerprint, pagination, bytes: response.body.length };
+            };
+            let verifiedBytes = 0;
+            if (cursor) {
+                // Offset APIs cannot guarantee a snapshot. Refuse shifted/edited boundaries instead of claiming completeness.
+                const previous = await read(cursor.page - 1);
+                verifiedBytes = previous.bytes;
+                if (previous.fingerprint !== cursor.previous || previous.pagination.totalCount !== cursor.total) {
+                    throw new AuditStop('tracker-changed');
+                }
+            }
+            const pageNumber = cursor?.page ?? 1;
+            const page = await read(pageNumber);
+            if (cursor && page.pagination.totalCount !== cursor.total)
+                throw new AuditStop('tracker-changed');
+            if (page.bytes + verifiedBytes > options.maxBytes)
+                throw new AuditStop('byte-budget');
+            // A full page lacking pagination headers needs one bounded probe, never a false complete result.
+            const next = page.pagination.nextPage ?? (!page.pagination.complete && page.pagination.items.length === size ? pageNumber + 1 : null);
+            if (next !== null && next <= pageNumber)
+                throw new AuditStop('cursor-invalidated');
+            return { items: page.items, bytes: page.bytes + verifiedBytes,
+                complete: next === null && page.pagination.complete,
+                nextCursor: next === null ? null : encodeAuditCursor({ scope, page: next, previous: page.fingerprint, total: page.pagination.totalCount }) };
+        },
+        async hydrate(issue, options) {
+            if (!/^[1-9]\d*$/.test(issue.id))
+                throw new AuditStop('invalid-issue-id');
+            const response = await transport(`${root}/${issue.id}`, options.signal);
+            if (response.body.length > options.maxBytes)
+                throw new AuditStop('byte-budget');
+            const raw = object(parseForgeJson(response));
+            if (raw.updated_at !== issue.updatedAt)
+                throw new AuditStop('tracker-changed');
+            const body = typeof raw.body === 'string' ? raw.body : '';
+            const comments = [];
+            let bytes = response.body.length;
+            const reader = createForgeReader(provider, async (path, signal) => {
+                const response = await transport(path, signal);
+                bytes += response.body.length;
+                if (bytes > options.maxBytes)
+                    throw new AuditStop('byte-budget');
+                return response;
+            }, { pageSize: 25 });
+            for (let page = 1;; page++) {
+                const result = await reader.listIssueComments(repository, Number(issue.id), page, options.signal);
+                comments.push(...result.items.map(c => c.body));
+                if (result.complete)
+                    break;
+                if (!result.items.length)
+                    throw new AuditStop('pagination-incomplete');
+                if (result.nextPage !== null && result.nextPage !== page + 1)
+                    throw new AuditStop('cursor-invalidated');
+                if (!result.nextPage && result.items.length < reader.pageSize)
+                    throw new AuditStop('pagination-incomplete');
+            }
+            return { body, comments, bytes };
+        },
+    };
+}
+//# sourceMappingURL=issue-pages.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.10.10",
+  "version": "2026.10.12",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,12 @@
     "tools/ralph-external/lib/worker-launch-cli.mjs",
     "tools/ralph-external/lib/worker-isolation.mjs",
     "tools/ralph-external/lib/worker-native-sandbox.mjs",
+    "tools/ralph-external/lib/worker-isolation-status.mjs",
+    "tools/ralph-external/lib/worker-retry-evidence.mjs",
+    "tools/ralph-external/lib/worker-termination.mjs",
+    "tools/ralph-external/lib/worker-invocation-processes.mjs",
+    "tools/ralph-external/lib/worker-invocation-ancestry.mjs",
+    "tools/ralph-external/lib/worker-context.mjs",
     "tools/ralph-external/lib/systemd-client.mjs",
     "tools/ralph-external/lib/consecutive-failure-circuit-breaker.mjs",
     "tools/ralph-external/lib/launcher-recovery-evidence.mjs",