@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/providers/types.d.ts

@@ -37,6 +37,35 @@ export interface ProviderDispatchEvent {
  * approximation.
  */
 export type ProviderDispatchObserver = (event: ProviderDispatchEvent) => Record<string, unknown>;
+/** Content-free completion observation for one already-admitted physical send. */
+export interface ProviderDispatchCompletionEvent {
+    provider: ProviderName;
+    operation: ProviderDispatchOperation;
+    attemptIndex: number;
+    model?: string;
+    outcome: 'ok' | 'error' | 'cancelled';
+    /**
+     * The physical boundary which just settled. A successful transport/process
+     * observation is deliberately not a successful provider result: parsers and
+     * stream consumers can still fail afterwards. Existing providers that do
+     * not report this field retain the historical final-result interpretation.
+     */
+    settlement?: 'transport' | 'process' | 'result';
+    httpStatus?: number;
+    /** Runtime-only classification input. Observers must never persist this raw value. */
+    error?: unknown;
+}
+export type ProviderDispatchCompletionObserver = (event: ProviderDispatchCompletionEvent) => void;
+/** A send that was refused before an HTTP request was admitted. */
+export interface ProviderDispatchRejectionEvent {
+    provider: ProviderName;
+    operation: ProviderDispatchOperation;
+    attemptIndex: number;
+    model?: string;
+    /** Runtime-only classification input; trace observers persist only its typed diagnostic. */
+    error: unknown;
+}
+export type ProviderDispatchRejectionObserver = (event: ProviderDispatchRejectionEvent) => void;
 export interface ProviderRunOptions {
     /** Optional model override; otherwise the provider picks a sane default. */
     model?: string;
@@ -56,6 +85,36 @@ export interface ProviderRunOptions {
     maxProviderDispatches?: number;
     /** Server-owned hook invoked immediately before every provider HTTP body send. */
     onProviderDispatch?: ProviderDispatchObserver;
+    /** Server-owned hook invoked when that same physical HTTP send settles. */
+    onProviderDispatchComplete?: ProviderDispatchCompletionObserver;
+    /** Server-owned hook invoked when admission rejects a would-be physical send. */
+    onProviderDispatchRejected?: ProviderDispatchRejectionObserver;
+    /**
+     * Server-owned lifecycle label for the physical send.  Providers must carry
+     * this through untouched; the local runtime is the only authority that maps
+     * it to an egress receipt and a trace span.  It exists so an immutable
+     * exploratory-plan correction cannot be miscounted as a second generation.
+     */
+    dispatchPhase?: import('@duckcodeailabs/dql-core').ProviderDispatchPhaseV1;
+    /**
+     * Server-owned sub-phase for the bounded analytical planner. It exists only
+     * to distinguish one initial proposal from one verifier-directed targeted
+     * revision at the local egress ledger; providers cannot use it to select a
+     * route or request another planner loop.
+     */
+    analyticalPlanningKind?: 'initial' | 'targeted_revision';
+    /**
+     * Server-owned egress purpose paired with {@link dispatchPhase}.  Ordinary
+     * Ask generation remains content-free; the only normal Ask repair purpose is
+     * `repair_sql` and it has no result-row permission.
+     */
+    egressPurpose?: import('@duckcodeailabs/dql-core').ProviderEgressPurpose;
+    /**
+     * Server-owned lineage marker for one same-provider transient transport
+     * retry. Providers carry it through to the local ledger; callers cannot use
+     * it to reopen planning or route selection.
+     */
+    retryOfAttemptIndex?: number;
 }
 export interface AgentToolDefinition {
     name: string;
@@ -63,6 +122,43 @@ export interface AgentToolDefinition {
     inputSchema: Record<string, unknown>;
     run(args: unknown): Promise<unknown>;
 }
+/**
+ * A server-owned update to an in-flight tool conversation.
+ *
+ * Native tool transports obtain this immediately before every provider send;
+ * text transports append the same instruction after every observation.  It
+ * lets a bounded controller narrow discovery to the next safe action without
+ * making a second, hidden planner call or trusting a provider to remember a
+ * stale tool list.
+ */
+export interface ProviderCurrentToolPolicy {
+    /** Canonical tools the provider may request on its next turn. */
+    allowedToolNames: readonly string[];
+    /** Safe, provider-visible explanation of why the set changed. */
+    instruction?: string;
+    /**
+     * At a physical-send reserve, one of these tools may be the final action.
+     * This is intentionally separate from `allowedToolNames`: ordinary tools
+     * must never use the last controller turn as a discovery escape hatch.
+     */
+    terminalActionToolNames?: readonly string[];
+}
+/**
+ * Host-owned phase decision for one concrete provider send.
+ *
+ * A native tool provider can issue several HTTP requests from one logical
+ * `generateWithTools` call.  The outer Ask runtime is the only component that
+ * knows whether its state has advanced from discovery/execution to the one
+ * required, post-result `finish_answer` control.  This callback lets that
+ * runtime classify each physical send at the transport boundary without
+ * serializing mutable state to a provider or granting a provider a lifecycle
+ * capability.
+ */
+export type ProviderPhysicalDispatchPhaseResolver = (input: {
+    operation: ProviderDispatchOperation;
+    attemptIndex: number;
+    requestedPhase?: import('@duckcodeailabs/dql-core').ProviderDispatchPhaseV1;
+}) => import('@duckcodeailabs/dql-core').ProviderDispatchPhaseV1 | undefined;
 export interface ProviderToolLoopOptions extends ProviderRunOptions {
     /** Hard cap for provider-visible tool calls in this turn. Default 8. */
     maxToolCalls?: number;
@@ -82,6 +178,9 @@ export interface ProviderToolLoopOptions extends ProviderRunOptions {
         allowedResultRowTools?: Record<string, number>;
         resultRowBudgetGroupByTool?: Record<string, string>;
         cumulativeResultRowBudgets?: Record<string, number>;
+        /** Additional shape caps for bounded local Ask V2 row egress. */
+        maxResultColumns?: number;
+        maxResultCells?: number;
         onPayload?: (event: {
             toolName: string;
             output: unknown;
@@ -92,7 +191,38 @@ export interface ProviderToolLoopOptions extends ProviderRunOptions {
             budgetExhausted: boolean;
         }) => void;
     };
+    /**
+     * Optional live tool policy owned by the host runtime.  The callback is
+     * process-local and is never serialized to a provider.  It is evaluated at
+     * each transport turn so native and text protocols receive the same current
+     * allowed-tool set and safe progress instruction.
+     */
+    getCurrentToolPolicy?: () => ProviderCurrentToolPolicy | undefined;
+    /**
+     * Process-local physical-send phase resolver.  Only the local Ask runtime
+     * installs this. Providers carry it to the wrapper unchanged and may never
+     * use it to choose a route, tool, or egress purpose.
+     */
+    resolvePhysicalDispatchPhase?: ProviderPhysicalDispatchPhaseResolver;
+}
+/**
+ * Typed native-tool-loop stop. Native transports normally return final prose,
+ * but a live Ask V2 policy must distinguish a physical controller/tool budget
+ * stop from an answer. The result deliberately contains no provider payload
+ * beyond the already-sanitized final text.
+ */
+export interface NativeToolLoopStop {
+    version: 1;
+    /**
+     * A typed controller stop. Deadline stops deliberately remain distinct from
+     * a tool budget: callers can preserve an already validated result and show
+     * the actual run-boundary recovery action.
+     */
+    kind: 'tool_budget_exhausted' | 'provider_dispatch_budget_exhausted' | 'invalid_tool_response' | 'run_soft_target_exceeded' | 'run_deadline_insufficient';
+    text: string;
+    toolCalls: number;
 }
+export type NativeToolLoopResult = string | NativeToolLoopStop;
 export interface AgentProvider {
     readonly name: ProviderName;
     /**
@@ -105,7 +235,7 @@ export interface AgentProvider {
      * call supplied tools, append their observations, and resolve with the final
      * assistant text. Callers must keep a one-shot generate() fallback.
      */
-    generateWithTools?(messages: AgentMessage[], tools: AgentToolDefinition[], options?: ProviderToolLoopOptions): Promise<string>;
+    generateWithTools?(messages: AgentMessage[], tools: AgentToolDefinition[], options?: ProviderToolLoopOptions): Promise<NativeToolLoopResult>;
     /**
      * Optional token streaming. Calls `onDelta` with each text chunk as it arrives
      * and resolves with the full concatenated text. Providers that omit this fall

package/dist/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}

package/dist/providers/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqHH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAuB,EACvB,QAAwB,EACxB,OAA2B,EAC3B,OAAgC;IAEhC,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmQH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAuB,EACvB,QAAwB,EACxB,OAA2B,EAC3B,OAAgC;IAEhC,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/relationship-proof.d.ts

@@ -1,4 +1,43 @@
 import type { MetricCapabilityContract, ResolvedRelationshipProofV1 } from '@duckcodeailabs/dql-core';
+import type { AgentEvidenceCandidate } from './meaning-resolution.js';
+/**
+ * The immutable, snapshot-bound safety authority for a governed physical
+ * relationship. This is deliberately separate from a capability path ID:
+ * the path identifies the edge the compiler may use, while this receipt pins
+ * the certification and warehouse-validation facts that made that edge safe
+ * when the plan froze.
+ *
+ * This lives beside the local resolved plan rather than the cross-surface
+ * semantic proof contract because it describes DQL's local physical registry,
+ * not an adapter-native semantic path. Old persisted plans remain readable;
+ * a newly compiled cross-entity governed plan must carry this authority.
+ */
+export interface GovernedRelationshipSafetyProofV1 {
+    version: 1;
+    relationshipPathId: string;
+    relationshipId: string;
+    from: string;
+    to: string;
+    keys: Array<{
+        from: string;
+        to: string;
+    }>;
+    status: 'certified';
+    cardinality: 'one_to_one' | 'one_to_many' | 'many_to_one';
+    fanout: 'safe';
+    staleCertification: false;
+    automaticJoinAllowed: true;
+    certificationFingerprint: string;
+    validation: {
+        status: 'passed';
+        checkedAt: string;
+        queryFingerprint: string;
+        proofFingerprint: string;
+    };
+    evidenceExpiresAt?: string;
+    snapshotId: string;
+    authorityFingerprint: string;
+}
 /** Build the sole normalized relationship authority for already selected dimensions. */
 export declare function buildResolvedRelationshipProofsV1(input: {
     capability: MetricCapabilityContract;
@@ -8,6 +47,48 @@ export declare function buildResolvedRelationshipProofsV1(input: {
     executionId: string;
     snapshotId: string;
 }): ResolvedRelationshipProofV1[];
+/**
+ * Return true only for a cross-model dimension whose capability preserves the
+ * exact adapter-native spelling and a non-empty entity path. A leaf name,
+ * broad result grain, or DQL relationship is not semantic compiler proof.
+ *
+ * Own-model dimensions use the primary entity and do not require a
+ * relationship proof; callers can handle that case separately.
+ */
+export declare function semanticDimensionUsesExactAdapterGrouping(capability: MetricCapabilityContract, dimension: MetricCapabilityContract['dimensions'][number]): boolean;
+/**
+ * Return true only when a cross-entity governed capability dimension carries
+ * a concrete relationship path that is backed by the *same snapshot's*
+ * certified, fresh, automatic, fanout-safe proof records.
+ *
+ * `resultGrainIds` is intentionally not authority here. It can describe the
+ * shape an adapter hopes to return, but cannot prove that the governed DQL
+ * compiler has an approved graph from the selected metric entity to the
+ * selected dimension. Likewise, a friendly relationship ID without its
+ * structured safety record is retrieval evidence, not a join authorization.
+ */
+export declare function governedCapabilityDimensionHasFreshAutomaticRelationshipProofV1(input: {
+    capability: MetricCapabilityContract;
+    dimension: MetricCapabilityContract['dimensions'][number];
+    candidates: readonly AgentEvidenceCandidate[];
+    /** Captured by the caller when deterministic tests need a stable clock. */
+    now?: number;
+}): boolean;
+/**
+ * Capture the precise snapshot safety records used by each selected
+ * cross-entity governed dimension. The caller persists these in the frozen
+ * plan so a registry cannot be silently restamped after planning.
+ */
+export declare function buildGovernedRelationshipSafetyProofsV1(input: {
+    capability: MetricCapabilityContract;
+    dimensions: readonly MetricCapabilityContract['dimensions'][number][];
+    candidates: readonly AgentEvidenceCandidate[];
+    snapshotId: string;
+    /** Captured by the caller when deterministic tests need a stable clock. */
+    now?: number;
+}): GovernedRelationshipSafetyProofV1[];
+/** Reject a mutated persisted plan proof before it can authorize SQL. */
+export declare function governedRelationshipSafetyProofIsSelfConsistentV1(proof: GovernedRelationshipSafetyProofV1): boolean;
 export declare function resolvedRelationshipProofMatches(input: {
     proof: ResolvedRelationshipProofV1;
     capability: MetricCapabilityContract;

package/dist/relationship-proof.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-proof.d.ts","sourceRoot":"","sources":["../src/relationship-proof.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAElC,wFAAwF;AACxF,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACvD,UAAU,EAAE,wBAAwB,CAAC;IACrC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,wBAAwB,CAAC,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,2BAA2B,EAAE,CAwChC;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,KAAK,EAAE,2BAA2B,CAAC;IACnC,UAAU,EAAE,wBAAwB,CAAC;IACrC,KAAK,EAAE,wBAAwB,CAAC,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAYV"}
+{"version":3,"file":"relationship-proof.d.ts","sourceRoot":"","sources":["../src/relationship-proof.ts"],"names":[],"mappings":"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"}

package/dist/relationship-proof.js

@@ -14,11 +14,16 @@ export function buildResolvedRelationshipProofsV1(input) {
         const nativeGroupingPath = dimension.nativeGroupingPath === undefined
             ? undefined
             : [...dimension.nativeGroupingPath];
-        const kind = relationshipPathIds.length > 0
-            ? 'dql_relationship_path'
-            : input.route === 'semantic' && Boolean(input.adapterId)
-                && Boolean(nativeGroupingReference) && nativeGroupingPath !== undefined
+        // A semantic adapter cannot consume a generic DQL relationship ID.
+        // Cross-model semantic execution is authorized only by the exact
+        // MetricFlow-native group-by frozen on this metric capability. Keep
+        // generic relationship paths for relational/exploratory routes only.
+        const kind = input.route === 'semantic'
+            ? semanticDimensionUsesExactAdapterGrouping(input.capability, dimension)
                 ? 'semantic_native_grouping'
+                : undefined
+            : relationshipPathIds.length > 0
+                ? 'dql_relationship_path'
                 : undefined;
         if (!kind)
             return [];
@@ -42,6 +47,190 @@ export function buildResolvedRelationshipProofsV1(input) {
     })
         .sort((left, right) => left.dimensionId.localeCompare(right.dimensionId));
 }
+/**
+ * Return true only for a cross-model dimension whose capability preserves the
+ * exact adapter-native spelling and a non-empty entity path. A leaf name,
+ * broad result grain, or DQL relationship is not semantic compiler proof.
+ *
+ * Own-model dimensions use the primary entity and do not require a
+ * relationship proof; callers can handle that case separately.
+ */
+export function semanticDimensionUsesExactAdapterGrouping(capability, dimension) {
+    if (dimension.entityId === capability.primaryEntityId)
+        return false;
+    if (!capability.executionCapabilities.some((execution) => execution.route === 'semantic' && Boolean(execution.adapterId?.trim())))
+        return false;
+    const nativeGroupingReference = dimension.nativeGroupingReference?.trim();
+    const nativeGroupingPath = dimension.nativeGroupingPath?.map((part) => part.trim()).filter(Boolean) ?? [];
+    if (!nativeGroupingReference || nativeGroupingPath.length === 0)
+        return false;
+    const leaf = semanticDimensionLeaf(dimension.dimensionId);
+    return Boolean(leaf) && nativeGroupingReference === [...nativeGroupingPath, leaf].join('__');
+}
+/**
+ * Return true only when a cross-entity governed capability dimension carries
+ * a concrete relationship path that is backed by the *same snapshot's*
+ * certified, fresh, automatic, fanout-safe proof records.
+ *
+ * `resultGrainIds` is intentionally not authority here. It can describe the
+ * shape an adapter hopes to return, but cannot prove that the governed DQL
+ * compiler has an approved graph from the selected metric entity to the
+ * selected dimension. Likewise, a friendly relationship ID without its
+ * structured safety record is retrieval evidence, not a join authorization.
+ */
+export function governedCapabilityDimensionHasFreshAutomaticRelationshipProofV1(input) {
+    const { capability, dimension } = input;
+    if (dimension.entityId === capability.primaryEntityId)
+        return true;
+    return governedCapabilityDimensionSafetyProofsV1(input) !== undefined;
+}
+/**
+ * Capture the precise snapshot safety records used by each selected
+ * cross-entity governed dimension. The caller persists these in the frozen
+ * plan so a registry cannot be silently restamped after planning.
+ */
+export function buildGovernedRelationshipSafetyProofsV1(input) {
+    const proofs = input.dimensions.flatMap((dimension) => {
+        if (dimension.entityId === input.capability.primaryEntityId)
+            return [];
+        return governedCapabilityDimensionSafetyProofsV1({
+            capability: input.capability,
+            dimension,
+            candidates: input.candidates,
+            ...(input.now === undefined ? {} : { now: input.now }),
+            snapshotId: input.snapshotId,
+        }) ?? [];
+    });
+    return [...new Map(proofs.map((proof) => [proof.authorityFingerprint, proof])).values()]
+        .sort((left, right) => left.relationshipPathId.localeCompare(right.relationshipPathId)
+        || left.relationshipId.localeCompare(right.relationshipId));
+}
+function governedCapabilityDimensionSafetyProofsV1(input) {
+    const { capability, dimension } = input;
+    if (dimension.entityId === capability.primaryEntityId)
+        return [];
+    const pathIds = new Map((dimension.relationshipPathIds ?? [])
+        .map((pathId) => [normalizeRelationshipIdentity(pathId), pathId.trim()])
+        .filter(([normalized, original]) => Boolean(normalized && original)));
+    if (pathIds.size === 0)
+        return undefined;
+    const proofsByPathId = new Map();
+    for (const candidate of input.candidates) {
+        if (candidate.eligible === false)
+            continue;
+        const referenced = new Set((candidate.relationshipEvidence ?? [])
+            .map(normalizeRelationshipIdentity)
+            .filter(Boolean));
+        if (referenced.size === 0)
+            continue;
+        for (const safety of candidate.relationshipSafety ?? []) {
+            if (!relationshipSafetyAllowsFreshAutomaticGovernedProof(safety, input.now))
+                continue;
+            const identities = relationshipSafetyIdentities(safety);
+            // A safety object detached from the carrier's relationship evidence is
+            // not snapshot authority. This mirrors the router's join gate and
+            // prevents a neighboring, unrelated proof from satisfying a path ID.
+            if (!identities.some((identity) => referenced.has(identity)))
+                continue;
+            for (const pathId of pathIds.keys()) {
+                if (identities.includes(pathId))
+                    proofsByPathId.set(pathId, safety);
+            }
+        }
+    }
+    if (proofsByPathId.size !== pathIds.size)
+        return undefined;
+    // A collection of individually safe proofs still must describe an actual
+    // graph from the selected metric entity to this exact cross-entity field.
+    // Do not infer a traversal from names, result grain, or shared leaves.
+    const adjacency = new Map();
+    const connect = (left, right) => {
+        if (!adjacency.has(left))
+            adjacency.set(left, new Set());
+        if (!adjacency.has(right))
+            adjacency.set(right, new Set());
+        adjacency.get(left).add(right);
+        adjacency.get(right).add(left);
+    };
+    for (const proof of proofsByPathId.values()) {
+        const from = normalizeRelationshipIdentity(proof.from ?? '');
+        const to = normalizeRelationshipIdentity(proof.to ?? '');
+        if (!from || !to)
+            return undefined;
+        connect(from, to);
+    }
+    const source = normalizeRelationshipIdentity(capability.primaryEntityId);
+    const target = normalizeRelationshipIdentity(dimension.entityId);
+    if (!source || !target)
+        return undefined;
+    const pending = [source];
+    const seen = new Set(pending);
+    while (pending.length > 0) {
+        const current = pending.shift();
+        if (current === target) {
+            return [...proofsByPathId.entries()]
+                .map(([normalizedPathId, safety]) => governedRelationshipSafetyProof({
+                relationshipPathId: pathIds.get(normalizedPathId),
+                safety,
+                ...(input.snapshotId ? { snapshotId: input.snapshotId } : {}),
+            }));
+        }
+        for (const next of adjacency.get(current) ?? []) {
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            pending.push(next);
+        }
+    }
+    return undefined;
+}
+function governedRelationshipSafetyProof(input) {
+    const validation = input.safety.validation;
+    // Callers reach this only after `relationshipSafetyAllowsFreshAutomatic…`.
+    // Keep the explicit assertions here so an independent future caller cannot
+    // accidentally serialize a partial safety record into a frozen plan.
+    if (!relationshipSafetyAllowsFreshAutomaticGovernedProof(input.safety)
+        || !validation
+        || !input.safety.from
+        || !input.safety.to
+        || !input.safety.certificationFingerprint
+        || !validation.checkedAt
+        || !validation.queryFingerprint
+        || !validation.proofFingerprint
+        || !['one_to_one', 'one_to_many', 'many_to_one'].includes(input.safety.cardinality ?? '')) {
+        throw new Error('Cannot serialize an invalid governed relationship safety proof.');
+    }
+    const body = {
+        version: 1,
+        relationshipPathId: input.relationshipPathId,
+        relationshipId: input.safety.id,
+        from: input.safety.from,
+        to: input.safety.to,
+        keys: [...input.safety.keys]
+            .map((key) => ({ from: key.from, to: key.to }))
+            .sort((left, right) => `${left.from}:${left.to}`.localeCompare(`${right.from}:${right.to}`)),
+        status: 'certified',
+        cardinality: input.safety.cardinality,
+        fanout: 'safe',
+        staleCertification: false,
+        automaticJoinAllowed: true,
+        certificationFingerprint: input.safety.certificationFingerprint,
+        validation: {
+            status: 'passed',
+            checkedAt: validation.checkedAt,
+            queryFingerprint: validation.queryFingerprint,
+            proofFingerprint: validation.proofFingerprint,
+        },
+        ...(input.safety.evidenceExpiresAt ? { evidenceExpiresAt: input.safety.evidenceExpiresAt } : {}),
+        snapshotId: input.snapshotId ?? 'snapshot-unavailable',
+    };
+    return { ...body, authorityFingerprint: fingerprint(body) };
+}
+/** Reject a mutated persisted plan proof before it can authorize SQL. */
+export function governedRelationshipSafetyProofIsSelfConsistentV1(proof) {
+    const { authorityFingerprint, ...body } = proof;
+    return fingerprint(body) === authorityFingerprint;
+}
 export function resolvedRelationshipProofMatches(input) {
     const expected = buildResolvedRelationshipProofsV1({
         capability: input.capability,
@@ -58,6 +247,41 @@ export function resolvedRelationshipProofMatches(input) {
 function fingerprint(value) {
     return createHash('sha256').update(stableStringify(value)).digest('hex');
 }
+function relationshipSafetyAllowsFreshAutomaticGovernedProof(safety, now = Date.now()) {
+    const validation = safety.validation;
+    const checkedAt = Date.parse(validation?.checkedAt ?? '');
+    const expiresAt = safety.evidenceExpiresAt === undefined
+        ? undefined
+        : Date.parse(safety.evidenceExpiresAt);
+    return safety.status === 'certified'
+        && safety.staleCertification === false
+        && safety.automaticJoinAllowed === true
+        && safety.fanout === 'safe'
+        && ['one_to_one', 'one_to_many', 'many_to_one'].includes(safety.cardinality ?? '')
+        && Boolean(safety.from?.trim() && safety.to?.trim())
+        && Boolean(safety.certificationFingerprint?.trim())
+        && Boolean(validation)
+        && validation?.status === 'passed'
+        && Boolean(validation?.queryFingerprint?.trim())
+        && Boolean(validation?.proofFingerprint?.trim())
+        && Number.isFinite(checkedAt)
+        && (expiresAt === undefined || Number.isFinite(expiresAt) && expiresAt > now)
+        && safety.keys.length > 0
+        && safety.keys.every((key) => Boolean(key.from.trim() && key.to.trim()));
+}
+function relationshipSafetyIdentities(safety) {
+    return uniqueSorted([safety.id, ...(safety.aliases ?? [])]
+        .map(normalizeRelationshipIdentity)
+        .filter(Boolean));
+}
+function normalizeRelationshipIdentity(value) {
+    return value.trim().toLowerCase();
+}
+function semanticDimensionLeaf(dimensionId) {
+    const local = dimensionId.split(':').at(-1)?.trim();
+    const leaf = local?.split('.').at(-1)?.trim();
+    return leaf || undefined;
+}
 function stableStringify(value) {
     if (Array.isArray(value))
         return `[${value.map(stableStringify).join(',')}]`;

package/dist/relationship-proof.js.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-proof.js","sourceRoot":"","sources":["../src/relationship-proof.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relationship-proof.js","sourceRoot":"","sources":["../src/relationship-proof.ts"],"names":[],"mappings":"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"}

package/dist/requirement-clauses.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The single grammar for time-window clauses.
+ *
+ * Three question parsers each carried their own relative-time regexes, every
+ * one requiring the determiner to sit adjacent to the time noun — so "last
+ * month" parsed and "last two months" did not, anywhere. The phrase then
+ * degraded to a bare `month` grouping while its count was misread as a row
+ * limit, and the answer silently changed meaning.
+ *
+ * This module is the one producer of the typed window. Its accepted forms
+ * deliberately MIRROR `resolvePlanTimeRange` (resolved-analytical-plan.ts) —
+ * the already-written resolver of "last N units" into UTC bounds — so the
+ * producer and the resolver cannot drift: everything parsed here resolves
+ * there, via the canonical digits `expression`.
+ */
+import type { AnalyticalTimeWindowV1 } from './analytical-orchestration.js';
+/**
+ * Parse a relative or named time window from free text. Returns undefined
+ * when the question carries no bounded period — a bare grain ("by month") is
+ * a grouping, not a window, and stays out of this clause on purpose.
+ */
+export declare function parseAnalyticalTimeWindow(question: string): AnalyticalTimeWindowV1 | undefined;
+//# sourceMappingURL=requirement-clauses.d.ts.map

package/dist/requirement-clauses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-clauses.d.ts","sourceRoot":"","sources":["../src/requirement-clauses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAS5E;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CA8C9F"}