@aiwg/cli 2026.7.20 → 2026.7.21

package/dist/src/sessions/candidates.js

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+import { IntelligenceCandidateSchema, IntelligenceCandidateTypeSchema, SESSION_CONTRACT_VERSION, SessionContractError, sha256, } from './contracts.js';
+export const ExtractedCandidateDraftSchema = z.object({
+    type: IntelligenceCandidateTypeSchema,
+    assertion: z.string().min(1),
+    subject: z.string().min(1).nullable(),
+    predicate: z.string().min(1).nullable(),
+    object: z.string().min(1).nullable(),
+    evidence: z.array(z.object({
+        eventId: z.string().min(1),
+        start: z.number().int().nonnegative(),
+        end: z.number().int().positive(),
+    }).strict()).min(1),
+    confidence: z.number().min(0).max(1),
+    conflictsWith: z.array(z.string().min(1)).default([]),
+    supersedes: z.array(z.string().min(1)).default([]),
+}).strict().superRefine((candidate, context) => {
+    if (candidate.type === 'relationship'
+        && (!candidate.subject || !candidate.predicate || !candidate.object)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'relationship candidates require subject, predicate, and object',
+        });
+    }
+});
+export class CandidateExtractionService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async extract(input) {
+        const evidenceById = new Map(input.documents.map((document) => [document.eventId, document]));
+        const raw = await input.extractor.extract(input.documents.map((document) => Object.freeze({
+            eventId: document.eventId,
+            text: document.searchableText,
+            role: document.role,
+        })));
+        const drafts = z.array(ExtractedCandidateDraftSchema).parse(raw);
+        const candidates = drafts
+            .filter((draft) => draft.confidence >= input.policy.minimumConfidence)
+            .map((draft) => {
+            const evidence = draft.evidence.map((span) => {
+                const document = evidenceById.get(span.eventId);
+                if (!document) {
+                    throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'candidate cites evidence outside the authorized extraction scope');
+                }
+                if (span.start >= span.end || span.end > document.searchableText.length) {
+                    throw new SessionContractError('MALFORMED_SOURCE', 'candidate evidence span is invalid');
+                }
+                const quote = document.searchableText.slice(span.start, span.end);
+                if (!quote.trim()) {
+                    throw new SessionContractError('MALFORMED_SOURCE', 'candidate evidence span must contain redacted source text');
+                }
+                return {
+                    ...span,
+                    quoteDigest: sha256(quote),
+                    quote,
+                };
+            });
+            const sensitivity = evidence.some((span) => evidenceById.get(span.eventId)?.sensitivity === 'sensitive') ? 'sensitive' : 'none';
+            if (!evidence.some((span) => evidenceSupportsAssertion(draft.assertion, span.quote))) {
+                throw new SessionContractError('MALFORMED_SOURCE', 'candidate assertion is not supported by its cited redacted evidence span');
+            }
+            const security = classifyCandidateSecurity({
+                assertion: draft.assertion,
+                subject: draft.subject,
+                predicate: draft.predicate,
+                object: draft.object,
+            });
+            return IntelligenceCandidateSchema.parse({
+                contractVersion: SESSION_CONTRACT_VERSION,
+                candidateId: stableCandidateId(draft),
+                version: 1,
+                type: draft.type,
+                assertion: draft.assertion,
+                subject: draft.subject,
+                predicate: draft.predicate,
+                object: draft.object,
+                evidence,
+                confidence: draft.confidence,
+                temporalScope: input.policy.temporalScope,
+                projectScope: input.policy.projectScope,
+                extractionMethod: input.extractor.method,
+                extractionVersion: input.extractor.version,
+                extractionPolicyVersion: input.policy.version,
+                model: input.extractor.model,
+                sensitivity,
+                security,
+                reviewState: 'pending',
+                conflictsWith: draft.conflictsWith,
+                supersedes: draft.supersedes,
+                createdAt: new Date().toISOString(),
+            });
+        });
+        return this.store.saveCandidates(candidates);
+    }
+}
+export class StructuralCandidateExtractor {
+    method = 'structural-labels';
+    version = '1.0.0';
+    model = null;
+    extract(evidence) {
+        const drafts = [];
+        for (const item of evidence) {
+            let offset = 0;
+            for (const line of item.text.split(/\n/)) {
+                const match = STRUCTURAL_PATTERN.exec(line);
+                if (match) {
+                    const label = match[1].toLowerCase();
+                    const assertion = match[2].trim();
+                    const start = offset + line.indexOf(assertion);
+                    const type = STRUCTURAL_TYPES[label];
+                    const relationship = type === 'relationship'
+                        ? parseRelationship(assertion)
+                        : { subject: null, predicate: null, object: null };
+                    if (type && (type !== 'relationship' || relationship.subject)) {
+                        drafts.push({
+                            type,
+                            assertion,
+                            ...relationship,
+                            evidence: [{ eventId: item.eventId, start, end: start + assertion.length }],
+                            confidence: 0.8,
+                            conflictsWith: [],
+                            supersedes: [],
+                        });
+                    }
+                }
+                offset += line.length + 1;
+            }
+        }
+        return drafts;
+    }
+}
+const SECURITY_POLICY_VERSION = '1.0.0';
+const INSTRUCTION_PATTERN = /\b(?:ignore|override|disregard)\b.{0,40}\b(?:instruction|prompt|policy|rule)s?\b|\b(?:system|developer)\s+(?:message|instruction|prompt)\b|\b(?:execute|invoke|run)\b.{0,30}\b(?:tool|command|shell|script)\b/i;
+const SECRET_PATTERN = /\b(?:api[_-]?key|access[_-]?token|password|passwd|private[_-]?key|authorization|cookie|secret)\b\s*(?:[:=]|\bis\b)/i;
+const STRUCTURE_PATTERN = /(?:^|\n)\s*(?:---|\.\.\.)\s*(?:\n|$)|```|~~~|<[/!?A-Za-z]|!\[[^\]]*\]\(|\[[^\]]+\]\([^)]*\)|\{\{|\{%/;
+const CONTROL_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/;
+const BIDI_PATTERN = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u;
+const LATIN_PATTERN = /\p{Script=Latin}/u;
+const CONFUSABLE_SCRIPT_PATTERN = /[\p{Script=Cyrillic}\p{Script=Greek}]/u;
+export function classifyCandidateSecurity(input) {
+    const text = [input.assertion, input.subject, input.predicate, input.object]
+        .filter((value) => Boolean(value))
+        .join('\n');
+    const warnings = [];
+    if (INSTRUCTION_PATTERN.test(text))
+        warnings.push('instruction-like');
+    if (STRUCTURE_PATTERN.test(text))
+        warnings.push('structure-breaking');
+    if (CONTROL_PATTERN.test(text))
+        warnings.push('control-character');
+    if (BIDI_PATTERN.test(text))
+        warnings.push('bidi-control');
+    if (LATIN_PATTERN.test(text) && CONFUSABLE_SCRIPT_PATTERN.test(text)) {
+        warnings.push('unicode-confusable');
+    }
+    if (/(?:javascript|data|vbscript):|<\s*(?:script|iframe|object|embed)\b/i.test(text)) {
+        warnings.push('active-content');
+    }
+    if (SECRET_PATTERN.test(text))
+        warnings.push('secret-bearing');
+    return {
+        disposition: warnings.length === 0 ? 'clear' : 'suspicious',
+        warnings: [...new Set(warnings)],
+        requiresAcknowledgement: warnings.length > 0,
+        acknowledged: false,
+        policyVersion: SECURITY_POLICY_VERSION,
+    };
+}
+function evidenceSupportsAssertion(assertion, quote) {
+    const tokens = (value) => new Set(value.normalize('NFKC').toLocaleLowerCase('en-US')
+        .match(/[\p{L}\p{N}]{3,}/gu) ?? []);
+    const assertionTokens = tokens(assertion);
+    const quoteTokens = tokens(quote);
+    return [...assertionTokens].some((token) => quoteTokens.has(token));
+}
+const STRUCTURAL_PATTERN = /^(Decision|Requirement|Constraint|Preference|Task|Discovery|Fix|Failed approach|Procedure|Risk|Contradiction|Question|Entity|Relationship):\s*(.+)$/i;
+const STRUCTURAL_TYPES = {
+    decision: 'decision',
+    requirement: 'requirement',
+    constraint: 'constraint',
+    preference: 'preference',
+    task: 'task',
+    discovery: 'discovery',
+    fix: 'fix',
+    'failed approach': 'failed-approach',
+    procedure: 'procedure',
+    risk: 'risk',
+    contradiction: 'contradiction',
+    question: 'question',
+    entity: 'entity',
+    relationship: 'relationship',
+};
+function parseRelationship(assertion) {
+    const parts = assertion.split('|').map((part) => part.trim());
+    return parts.length === 3 && parts.every(Boolean)
+        ? { subject: parts[0], predicate: parts[1], object: parts[2] }
+        : { subject: null, predicate: null, object: null };
+}
+function stableCandidateId(draft) {
+    return sha256(JSON.stringify({
+        type: draft.type,
+        evidenceEventIds: [...new Set(draft.evidence.map((span) => span.eventId))].sort(),
+        subject: draft.subject,
+        predicate: draft.predicate,
+        object: draft.object,
+    }));
+}
+//# sourceMappingURL=candidates.js.map

package/dist/src/sessions/contracts.js

@@ -0,0 +1,310 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const SESSION_CONTRACT_VERSION = '1.0.0';
+export const SESSION_PROVIDER_IDS = [
+    'claude', 'codex', 'copilot', 'cursor', 'factory', 'hermes',
+    'opencode', 'openclaw', 'openhuman', 'warp', 'devin-desktop', 'generic',
+];
+export const SessionProviderIdSchema = z.enum(SESSION_PROVIDER_IDS);
+export const SESSION_PROVIDER_ALIASES = Object.freeze({
+    windsurf: 'devin-desktop',
+});
+const CompatibleSessionProviderIdSchema = z.preprocess((value) => typeof value === 'string'
+    ? (SESSION_PROVIDER_ALIASES[value] ?? value)
+    : value, SessionProviderIdSchema);
+export const CapabilityDispositionSchema = z.enum([
+    'implemented', 'manual-only', 'degraded', 'unsupported',
+]);
+export const OperationalStateSchema = z.enum([
+    'available', 'unavailable', 'inaccessible', 'version-unknown',
+    'schema-unsupported', 'degraded',
+]);
+export const ConsistencyStateSchema = z.enum([
+    'provisional', 'consistent-snapshot', 'complete',
+]);
+export const SessionErrorCodeSchema = z.enum([
+    'UNKNOWN_PROVIDER', 'UNKNOWN_SCHEMA_MAJOR', 'SOURCE_NOT_AUTHORIZED',
+    'SOURCE_OUTSIDE_ALLOWED_ROOT', 'SOURCE_SYMLINK', 'SOURCE_NOT_REGULAR_FILE',
+    'RESOURCE_LIMIT_EXCEEDED', 'NETWORK_NOT_AUTHORIZED', 'SCHEMA_DRIFT',
+    'OPERATION_NOT_AUTHORIZED',
+    'IMPORT_CONFLICT', 'IMPORT_INTERRUPTED', 'MALFORMED_SOURCE',
+    'DUPLICATE_NATIVE_ID', 'AMBIGUOUS_TIMESTAMP', 'TRUNCATED_SOURCE',
+    'UNSUPPORTED_OPERATION',
+    'INVALID_SEARCH_QUERY',
+]);
+const VersionSchema = z.string().regex(/^\d+\.\d+\.\d+(?:[-+].+)?$/);
+const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const NativeExtensionsSchema = z.record(z.unknown()).superRefine((value, context) => {
+    for (const key of Object.keys(value)) {
+        if (!key.startsWith('native.')) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: `native extension must use native.<provider>: ${key}` });
+        }
+    }
+});
+export const SessionSourceSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    sourceId: z.string().min(1),
+    provider: CompatibleSessionProviderIdSchema,
+    providerProfile: z.string().min(1),
+    locatorClass: z.string().min(1),
+    redactedLocator: z.string().min(1),
+    adapterVersion: VersionSchema,
+    sourceSchemaVersion: VersionSchema,
+    disposition: CapabilityDispositionSchema,
+    operationalState: OperationalStateSchema,
+    consistency: ConsistencyStateSchema,
+    authorizedAt: z.string().datetime({ offset: true }),
+    extensions: NativeExtensionsSchema.default({}),
+});
+export const SessionEventSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    eventId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceId: z.string().min(1),
+    importRunId: z.string().min(1),
+    nativeId: z.string().min(1).nullable(),
+    sequence: z.number().int().nonnegative(),
+    kind: z.string().min(1),
+    role: z.string().min(1).nullable(),
+    participant: z.string().min(1).nullable().default(null),
+    toolName: z.string().min(1).nullable().default(null),
+    toolCallId: z.string().min(1).nullable().default(null),
+    model: z.string().min(1).nullable().default(null),
+    entities: z.array(z.string().min(1)).default([]),
+    extractionState: z.string().min(1).nullable().default(null),
+    occurredAt: z.string().datetime({ offset: true }).nullable(),
+    searchableText: z.string(),
+    digest: DigestSchema,
+    rawReference: z.object({
+        locatorClass: z.string().min(1),
+        offset: z.number().int().nonnegative().optional(),
+        sequence: z.number().int().nonnegative().optional(),
+    }),
+    adapterVersion: VersionSchema,
+    consistency: ConsistencyStateSchema,
+    sensitivity: z.object({
+        classification: z.enum(['none', 'sensitive']),
+        classes: z.array(z.string().min(1)),
+    }),
+    opaque: z.boolean().default(false),
+    extensions: NativeExtensionsSchema.default({}),
+});
+export const SessionSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    sessionId: z.string().min(1),
+    sourceId: z.string().min(1),
+    provider: CompatibleSessionProviderIdSchema,
+    nativeSessionId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    startedAt: z.string().datetime({ offset: true }).nullable(),
+    updatedAt: z.string().datetime({ offset: true }).nullable(),
+    consistency: ConsistencyStateSchema,
+    lifecycle: z.enum(['active', 'complete', 'tombstoned']),
+    sourceDigest: DigestSchema,
+    extensions: NativeExtensionsSchema.default({}),
+});
+export const ImportCheckpointSchema = z.object({
+    cursor: z.string(),
+    recordsRead: z.number().int().nonnegative(),
+    bytesRead: z.number().int().nonnegative(),
+    checkpointVersion: z.literal('2').optional(),
+    positionKind: z.enum(['record-index', 'byte-offset', 'provider-native']).optional(),
+    sourceGeneration: z.string().min(1).optional(),
+    locatorClass: z.string().min(1).optional(),
+    adapterVersion: VersionSchema.optional(),
+    sourceSchemaVersion: VersionSchema.optional(),
+    policyVersion: VersionSchema.optional(),
+    continuity: z.enum([
+        'new-generation',
+        'validated-append',
+        'unchanged-replay',
+        'unverified',
+    ]).optional(),
+    sourceSize: z.number().int().nonnegative().optional(),
+    sourceMtimeMs: z.number().nonnegative().optional(),
+    sourceFileIdentity: z.string().min(1).optional(),
+    prefixDigest: DigestSchema.optional(),
+});
+export const ImportRunSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    importRunId: z.string().min(1),
+    sourceId: z.string().min(1),
+    parserVersion: VersionSchema,
+    policyVersion: VersionSchema,
+    sourceSchemaVersion: VersionSchema,
+    consistency: ConsistencyStateSchema,
+    status: z.enum(['running', 'committed', 'rolled-back', 'failed']),
+    checkpoint: ImportCheckpointSchema,
+    startedAt: z.string().datetime({ offset: true }),
+    completedAt: z.string().datetime({ offset: true }).nullable(),
+    errorCode: SessionErrorCodeSchema.nullable(),
+});
+export const ProvenanceEdgeSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    edgeId: z.string().min(1),
+    relation: z.enum([
+        'acquired-from', 'normalized-from', 'derived-from', 'promoted-to',
+        'supersedes', 'invalidates',
+    ]),
+    fromId: z.string().min(1),
+    toId: z.string().min(1),
+    importRunId: z.string().min(1),
+    createdAt: z.string().datetime({ offset: true }),
+});
+export const IntelligenceCandidateTypeSchema = z.enum([
+    'decision', 'requirement', 'constraint', 'preference', 'task', 'discovery',
+    'fix', 'failed-approach', 'procedure', 'risk', 'contradiction', 'question',
+    'entity', 'relationship',
+]);
+export const CandidateSecurityWarningSchema = z.enum([
+    'instruction-like', 'structure-breaking', 'control-character', 'bidi-control',
+    'unicode-confusable', 'active-content', 'secret-bearing',
+]);
+export const CandidateSecuritySchema = z.object({
+    disposition: z.enum(['clear', 'suspicious']),
+    warnings: z.array(CandidateSecurityWarningSchema),
+    requiresAcknowledgement: z.boolean(),
+    acknowledged: z.boolean(),
+    policyVersion: VersionSchema,
+}).strict();
+export const IntelligenceCandidateSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    candidateId: z.string().min(1),
+    version: z.number().int().positive(),
+    type: IntelligenceCandidateTypeSchema,
+    assertion: z.string().min(1),
+    subject: z.string().min(1).nullable(),
+    predicate: z.string().min(1).nullable(),
+    object: z.string().min(1).nullable(),
+    evidence: z.array(z.object({
+        eventId: z.string().min(1),
+        start: z.number().int().nonnegative(),
+        end: z.number().int().positive(),
+        quoteDigest: DigestSchema,
+        quote: z.string().min(1).optional(),
+    }).strict()).min(1),
+    confidence: z.number().min(0).max(1),
+    temporalScope: z.string().min(1),
+    projectScope: z.string().min(1),
+    extractionMethod: z.string().min(1),
+    extractionVersion: VersionSchema,
+    extractionPolicyVersion: VersionSchema,
+    model: z.string().min(1).nullable(),
+    sensitivity: z.enum(['none', 'sensitive']),
+    security: CandidateSecuritySchema.default({
+        disposition: 'clear',
+        warnings: [],
+        requiresAcknowledgement: false,
+        acknowledged: false,
+        policyVersion: '1.0.0',
+    }),
+    reviewState: z.enum([
+        'pending', 'accepted', 'rejected', 'deferred', 'promoted', 'superseded',
+    ]),
+    conflictsWith: z.array(z.string().min(1)).default([]),
+    supersedes: z.array(z.string().min(1)).default([]),
+    createdAt: z.string().datetime({ offset: true }),
+}).strict().superRefine((candidate, context) => {
+    if (candidate.type === 'relationship'
+        && (!candidate.subject || !candidate.predicate || !candidate.object)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'relationship candidates require subject, predicate, and object',
+        });
+    }
+});
+export const CandidateReviewReceiptSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    receiptId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateVersion: z.number().int().positive(),
+    fromState: z.enum([
+        'pending', 'accepted', 'rejected', 'deferred', 'promoted', 'superseded',
+    ]),
+    toState: z.enum([
+        'pending', 'accepted', 'rejected', 'deferred', 'promoted', 'superseded',
+    ]),
+    reviewer: z.string().min(1),
+    reason: z.string().min(1),
+    securityWarnings: z.array(CandidateSecurityWarningSchema).default([]),
+    securityAcknowledged: z.boolean().default(false),
+    occurredAt: z.string().datetime({ offset: true }),
+}).strict();
+export const PromotionReceiptSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    receiptId: z.string().min(1),
+    operationId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateVersion: z.number().int().positive(),
+    consumer: z.string().min(1),
+    destinationRef: z.string().min(1),
+    reviewer: z.string().min(1),
+    approvedAt: z.string().datetime({ offset: true }),
+    evidenceEventIds: z.array(z.string().min(1)).min(1),
+    conflictsWith: z.array(z.string().min(1)),
+    supersedes: z.array(z.string().min(1)),
+    beforeHash: DigestSchema.nullable(),
+    afterHash: DigestSchema,
+    dryRun: z.boolean(),
+    duplicate: z.boolean(),
+}).strict();
+export const DeletionReceiptSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    receiptId: z.string().min(1),
+    operationId: z.string().min(1),
+    scopeClass: z.string().min(1),
+    counts: z.record(z.number().int().nonnegative()),
+    survivingDependentIds: z.array(z.string().min(1)),
+    actorClass: z.string().min(1),
+    reasonCode: z.string().min(1),
+    orphanCounts: z.record(z.number().int().nonnegative()),
+    outcome: z.enum(['preview', 'committed', 'failed']),
+    occurredAt: z.string().datetime({ offset: true }),
+}).strict();
+export const PromotionDependencyDecisionSchema = z.object({
+    dependentId: z.string().min(1),
+    action: z.enum([
+        'revoke', 'supersede', 'retain', 'origin_unavailable', 'delete', 'abort',
+    ]),
+    basis: z.string().min(1),
+}).strict();
+export function assertSessionProviderId(value) {
+    const canonical = SESSION_PROVIDER_ALIASES[value] ?? value;
+    const parsed = SessionProviderIdSchema.safeParse(canonical);
+    if (!parsed.success)
+        throw new SessionContractError('UNKNOWN_PROVIDER', `unknown session provider: ${value}`);
+    return parsed.data;
+}
+export function assertSupportedSchemaMajor(version, supportedMajor = 1) {
+    const match = /^(\d+)\./.exec(version);
+    if (!match || Number(match[1]) !== supportedMajor) {
+        throw new SessionContractError('UNKNOWN_SCHEMA_MAJOR', `unsupported session schema major: ${version}`);
+    }
+}
+export function stableSessionId(provider, sourceId, nativeSessionId) {
+    const canonical = assertSessionProviderId(provider);
+    // Preserve the legacy identity seed through the published compatibility
+    // window so existing Windsurf catalogs do not duplicate normalized rows.
+    const identitySeed = canonical === 'devin-desktop' ? 'windsurf' : canonical;
+    return stableId('session', identitySeed, sourceId, nativeSessionId);
+}
+export function stableEventId(sourceId, record, digest) {
+    return record.nativeEventId
+        ? stableId('event', sourceId, record.nativeEventId)
+        : stableId('event', sourceId, record.nativeSessionId, record.sequence, record.kind, digest);
+}
+export function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function stableId(prefix, ...parts) {
+    return `${prefix}_${createHash('sha256').update(parts.join('\0')).digest('hex')}`;
+}
+export class SessionContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SessionContractError';
+    }
+}
+//# sourceMappingURL=contracts.js.map

package/dist/src/sessions/discovery.js

@@ -0,0 +1,51 @@
+import { SessionContractError, assertSessionProviderId, } from './contracts.js';
+export class SessionSourceAdapterRegistry {
+    adapters = new Map();
+    register(adapter) {
+        const provider = assertSessionProviderId(adapter.provider);
+        if (this.adapters.has(provider))
+            throw new Error(`session adapter already registered: ${provider}`);
+        this.adapters.set(provider, adapter);
+    }
+    get(providerInput) {
+        const provider = assertSessionProviderId(providerInput);
+        const adapter = this.adapters.get(provider);
+        if (!adapter) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `no session adapter is registered for ${provider}`);
+        }
+        return adapter;
+    }
+    assertOperation(providerInput, operation) {
+        const adapter = this.get(providerInput);
+        if (!adapter.supportedOperations.includes(operation)) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', `${operation} is unsupported for provider ${adapter.provider}`);
+        }
+        return adapter;
+    }
+    async *discover(providerInput, scope) {
+        const adapter = this.assertOperation(providerInput, 'discover');
+        if (scope.allowedRoots.length === 0 && (scope.authorizedAccounts?.length ?? 0) === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'discovery requires at least one explicitly authorized root or account');
+        }
+        yield* adapter.discover({
+            ...scope,
+            allowedRoots: [...scope.allowedRoots],
+            authorizedAccounts: scope.authorizedAccounts ? [...scope.authorizedAccounts] : undefined,
+        });
+    }
+    report(providerInput, input) {
+        const adapter = this.get(providerInput);
+        return Object.freeze({
+            provider: adapter.provider,
+            classification: adapter.disposition,
+            supportedOperations: Object.freeze([...adapter.supportedOperations]),
+            acquisitionModes: Object.freeze([...adapter.acquisitionModes]),
+            ...input,
+        });
+    }
+}
+export function redactSourceLocator(locator) {
+    const leaf = locator.replaceAll('\\', '/').split('/').filter(Boolean).at(-1) ?? '<source>';
+    return `<session-source>/${leaf.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/src/sessions/fixtures.js

@@ -0,0 +1,12 @@
+export function defineSessionAdapterFixture(fixture) {
+    if (fixture.synthetic !== true)
+        throw new Error('session fixtures must be synthetic or separately redacted');
+    if (fixture.disposition === 'implemented' && fixture.records.length === 0) {
+        throw new Error('implemented adapters require at least one synthetic fixture record');
+    }
+    if (fixture.disposition !== 'implemented' && !fixture.unsupportedReason) {
+        throw new Error(`${fixture.disposition} fixtures require an explicit reason`);
+    }
+    return Object.freeze({ ...fixture, records: Object.freeze([...fixture.records]) });
+}
+//# sourceMappingURL=fixtures.js.map