@dsh-enhanced/assistant-work-items 0.0.0-stage → 0.1.67

package/lib/intake.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Deterministic intake ledger (WP20 slice 1).
+ *
+ * One durable row per `(source, sourceEventId)` records what the Host decided
+ * about an inbound item, from normalized metadata only. Nothing here reads a
+ * message body, calls a model, admits a work item or dispatches anything: the
+ * row is audit evidence that a later, evaluated slice can build on.
+ */
+export type WorkItemIntakeKind = 'message' | 'event';
+export type WorkItemIntakeDecision = 'stored' | 'duplicate' | 'filtered';
+export type WorkItemIntakeStrength = 'explicit' | 'inferred' | 'ignore';
+export type WorkItemIntakeStrengthReason = 'allowlisted-addressed' | 'thread-follow-up' | 'allowlisted-unaddressed' | 'bot-capped' | 'not-allowlisted' | 'follow-up-not-allowlisted';
+export type WorkItemIntakeReason = 'strength-explicit' | 'strength-inferred' | 'strength-ignore' | 'duplicate-content' | 'unaddressed-group-disabled' | 'unsubscribed-event-disabled';
+/**
+ * Host-normalized metadata for one inbound item.
+ *
+ * The field list is closed: any other key (for example `text` or `body`) is
+ * rejected, so a caller cannot hand message content to the ledger by mistake.
+ * `contentDigest` is an optional SHA-256 hex digest the Host computed over the
+ * content it already holds; it is the only content-derived value accepted.
+ */
+export interface WorkItemIntakeInput {
+    /** Host-registered inbound source, e.g. `lark-channel`. */
+    readonly source: string;
+    /** Stable source-local event id; the replay key together with `source`. */
+    readonly sourceEventId: string;
+    readonly kind: WorkItemIntakeKind;
+    readonly senderAllowlisted: boolean;
+    /** The item addresses the assistant (mention, direct message, command). */
+    readonly addressed: boolean;
+    /**
+     * The item follows up on a thread the ledger already tracks as work. Only an
+     * allowlisted sender's follow-up is explicit; any other follow-up is ignored.
+     */
+    readonly threadFollowUp: boolean;
+    readonly senderIsBot: boolean;
+    /** Messages only: posted in a group conversation. Defaults to `false`. */
+    readonly groupMessage?: boolean;
+    /** Events only: the owner subscribed to this event type. Defaults to `true`. */
+    readonly subscribed?: boolean;
+    readonly contentDigest?: string;
+    readonly occurredAt: number;
+}
+/** Per-source owner opt-ins; every flag defaults to off. */
+export interface WorkItemIntakeSourcePolicy {
+    readonly unaddressedGroupMessages: boolean;
+    readonly unsubscribedEvents: boolean;
+}
+export interface WorkItemIntakeSignals {
+    readonly senderAllowlisted: boolean;
+    readonly addressed: boolean;
+    readonly threadFollowUp: boolean;
+    readonly senderIsBot: boolean;
+    readonly groupMessage: boolean;
+    readonly subscribed: boolean;
+}
+/** Normalized input plus the Host-computed grade and pre-dedup decision. */
+export interface WorkItemIntakeCandidate {
+    readonly source: string;
+    readonly sourceEventId: string;
+    readonly kind: WorkItemIntakeKind;
+    readonly signals: WorkItemIntakeSignals;
+    readonly strength: WorkItemIntakeStrength;
+    readonly strengthReason: WorkItemIntakeStrengthReason;
+    /** `stored` may still become `duplicate` inside the store transaction. */
+    readonly decision: 'stored' | 'filtered';
+    readonly reason: WorkItemIntakeReason;
+    readonly contentDigest: string | null;
+    readonly metadataDigest: string;
+    readonly occurredAt: number;
+}
+export interface WorkItemIntakeRecord {
+    readonly source: string;
+    readonly sourceEventId: string;
+    readonly kind: WorkItemIntakeKind;
+    readonly decision: WorkItemIntakeDecision;
+    readonly reason: WorkItemIntakeReason;
+    readonly strength: WorkItemIntakeStrength;
+    readonly strengthReason: WorkItemIntakeStrengthReason;
+    readonly signals: WorkItemIntakeSignals;
+    readonly contentDigest: string | null;
+    readonly metadataDigest: string;
+    readonly occurredAt: number;
+    readonly recordedAt: number;
+}
+export interface WorkItemIntakeResult {
+    readonly record: WorkItemIntakeRecord;
+    /** True when the `(source, sourceEventId)` row already existed. */
+    readonly replayed: boolean;
+    /** Replay only: the replayed metadata digest differs from the original. */
+    readonly metadataChanged?: true;
+}
+export declare const INTAKE_SOURCE_ID: RegExp;
+/**
+ * Grade one item's strength from normalized metadata.
+ *
+ * The allowlist scopes both explicit paths: an allowlisted sender that
+ * addresses the assistant, or follows up on a tracked work thread, is
+ * `explicit`; allowlisted but otherwise unaddressed is `inferred`; anything
+ * else, including a non-allowlisted follow-up, is `ignore`. A bot sender is
+ * never stronger than `inferred`.
+ */
+export declare function gradeIntakeStrength(signals: Pick<WorkItemIntakeSignals, 'senderAllowlisted' | 'addressed' | 'threadFollowUp' | 'senderIsBot'>): {
+    readonly strength: WorkItemIntakeStrength;
+    readonly reason: WorkItemIntakeStrengthReason;
+};
+/**
+ * Validate one input and compute its grade and pre-dedup decision.
+ *
+ * An `ignore` grade is `filtered`. Source opt-in filters then apply: a group
+ * message that is neither addressed nor an allowlisted follow-up, or an
+ * unsubscribed event, is `filtered` unless the owner enabled that source.
+ * Everything else is `stored` (metadata only).
+ */
+export declare function classifyIntake(raw: WorkItemIntakeInput, policy?: WorkItemIntakeSourcePolicy): WorkItemIntakeCandidate;
+/** Resolve the owner opt-ins for one source; unknown sources stay fully off. */
+export declare function intakeSourcePolicy(sources: Readonly<Record<string, WorkItemIntakeSourcePolicy>> | undefined, source: string): WorkItemIntakeSourcePolicy;
+//# sourceMappingURL=intake.d.ts.map

package/lib/intake.d.ts.map

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

package/lib/intake.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { WorkItemError } from "./types.js";
+const INPUT_KEYS = ['source', 'sourceEventId', 'kind', 'senderAllowlisted', 'addressed', 'threadFollowUp', 'senderIsBot',
+    'groupMessage', 'subscribed', 'contentDigest', 'occurredAt'];
+export const INTAKE_SOURCE_ID = /^[a-z][a-z0-9-]{0,63}$/u;
+const SHA256_HEX = /^[0-9a-f]{64}$/u;
+const MAX_EVENT_ID_BYTES = 256;
+// C0/C1 controls and line/paragraph separators never belong in an id.
+function hasControl(value) {
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029)
+            return true;
+    }
+    return false;
+}
+const DISABLED_POLICY = Object.freeze({ unaddressedGroupMessages: false, unsubscribedEvents: false });
+function fail(code, message) {
+    throw new WorkItemError(code, message);
+}
+function flag(value, field, fallback) {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        fail('invalid-input', `intake ${field} must be a boolean`);
+    return value;
+}
+/**
+ * Grade one item's strength from normalized metadata.
+ *
+ * The allowlist scopes both explicit paths: an allowlisted sender that
+ * addresses the assistant, or follows up on a tracked work thread, is
+ * `explicit`; allowlisted but otherwise unaddressed is `inferred`; anything
+ * else, including a non-allowlisted follow-up, is `ignore`. A bot sender is
+ * never stronger than `inferred`.
+ */
+export function gradeIntakeStrength(signals) {
+    let strength;
+    let reason;
+    if (signals.senderAllowlisted && signals.addressed)
+        [strength, reason] = ['explicit', 'allowlisted-addressed'];
+    else if (signals.senderAllowlisted && signals.threadFollowUp)
+        [strength, reason] = ['explicit', 'thread-follow-up'];
+    else if (signals.senderAllowlisted)
+        [strength, reason] = ['inferred', 'allowlisted-unaddressed'];
+    else if (signals.threadFollowUp)
+        [strength, reason] = ['ignore', 'follow-up-not-allowlisted'];
+    else
+        [strength, reason] = ['ignore', 'not-allowlisted'];
+    if (signals.senderIsBot && strength === 'explicit')
+        [strength, reason] = ['inferred', 'bot-capped'];
+    return Object.freeze({ strength, reason });
+}
+/** Stable digest over the normalized metadata only; never over content. */
+function metadataDigest(fields) {
+    const canonical = JSON.stringify(Object.keys(fields).sort().map(key => [key, fields[key]]));
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+/**
+ * Validate one input and compute its grade and pre-dedup decision.
+ *
+ * An `ignore` grade is `filtered`. Source opt-in filters then apply: a group
+ * message that is neither addressed nor an allowlisted follow-up, or an
+ * unsubscribed event, is `filtered` unless the owner enabled that source.
+ * Everything else is `stored` (metadata only).
+ */
+export function classifyIntake(raw, policy = DISABLED_POLICY) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        fail('invalid-input', 'intake input must be an object');
+    const value = raw;
+    for (const key of Object.keys(value)) {
+        if (!INPUT_KEYS.includes(key))
+            fail('invalid-input', `intake input contains unknown field ${key}`);
+    }
+    const source = value['source'];
+    if (typeof source !== 'string' || !INTAKE_SOURCE_ID.test(source))
+        fail('invalid-input', 'intake source has an invalid shape');
+    const eventId = value['sourceEventId'];
+    if (typeof eventId !== 'string' || eventId.length === 0 || eventId !== eventId.trim() || hasControl(eventId)
+        || Buffer.byteLength(eventId, 'utf8') > MAX_EVENT_ID_BYTES) {
+        fail('invalid-input', `intake sourceEventId must be 1-${MAX_EVENT_ID_BYTES} bytes without control characters`);
+    }
+    const kind = value['kind'];
+    if (kind !== 'message' && kind !== 'event')
+        fail('invalid-input', "intake kind must be 'message' or 'event'");
+    if (kind === 'message' && value['subscribed'] !== undefined)
+        fail('invalid-input', 'intake subscribed applies to events only');
+    if (kind === 'event' && value['groupMessage'] !== undefined)
+        fail('invalid-input', 'intake groupMessage applies to messages only');
+    const signals = Object.freeze({
+        senderAllowlisted: flag(value['senderAllowlisted'], 'senderAllowlisted'),
+        addressed: flag(value['addressed'], 'addressed'),
+        threadFollowUp: flag(value['threadFollowUp'], 'threadFollowUp'),
+        senderIsBot: flag(value['senderIsBot'], 'senderIsBot'),
+        groupMessage: flag(value['groupMessage'], 'groupMessage', false),
+        subscribed: flag(value['subscribed'], 'subscribed', true),
+    });
+    const rawDigest = value['contentDigest'];
+    if (rawDigest !== undefined && (typeof rawDigest !== 'string' || !SHA256_HEX.test(rawDigest))) {
+        fail('invalid-input', 'intake contentDigest must be a lowercase SHA-256 hex digest');
+    }
+    const contentDigest = rawDigest === undefined ? null : rawDigest;
+    const occurredAt = value['occurredAt'];
+    if (typeof occurredAt !== 'number' || !Number.isSafeInteger(occurredAt) || occurredAt < 0)
+        fail('invalid-input', 'intake occurredAt must be a non-negative integer');
+    const grade = gradeIntakeStrength(signals);
+    let decision = grade.strength === 'ignore' ? 'filtered' : 'stored';
+    let reason = grade.strength === 'explicit' ? 'strength-explicit' : grade.strength === 'inferred' ? 'strength-inferred' : 'strength-ignore';
+    // A follow-up counts as addressed only for an allowlisted sender.
+    const directed = signals.addressed || (signals.threadFollowUp && signals.senderAllowlisted);
+    if (kind === 'message' && signals.groupMessage && !directed && !policy.unaddressedGroupMessages) {
+        [decision, reason] = ['filtered', 'unaddressed-group-disabled'];
+    }
+    else if (kind === 'event' && !signals.subscribed && !policy.unsubscribedEvents) {
+        [decision, reason] = ['filtered', 'unsubscribed-event-disabled'];
+    }
+    return Object.freeze({
+        source,
+        sourceEventId: eventId,
+        kind,
+        signals,
+        strength: grade.strength,
+        strengthReason: grade.reason,
+        decision,
+        reason,
+        contentDigest,
+        metadataDigest: metadataDigest({ source, sourceEventId: eventId, kind, ...signals, contentDigest, occurredAt }),
+        occurredAt,
+    });
+}
+/** Resolve the owner opt-ins for one source; unknown sources stay fully off. */
+export function intakeSourcePolicy(sources, source) {
+    if (sources === undefined || !Object.hasOwn(sources, source))
+        return DISABLED_POLICY;
+    return sources[source];
+}
+//# sourceMappingURL=intake.js.map

package/lib/intake.js.map

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

package/lib/ledger.d.ts

@@ -0,0 +1,86 @@
+import type { NormalizedLimits } from './config.ts';
+import type { ClaimResult, ReportResult, ReclaimResult, WorkItemStore } from './store.ts';
+import type { WorkItemClaimRecord, WorkItemDispatchRecord, WorkItemDeliveryState, WorkItemEventRecord, WorkItemRecord, WorkItemReportRecord, WorkItemReportStatus, WorkItemState } from './types.ts';
+import type { WorkItemWorkspace } from './workspace.ts';
+/** A point-in-time view of one item and everything attached to it. */
+export interface WorkItemDetail {
+    readonly item: WorkItemRecord;
+    readonly events: readonly WorkItemEventRecord[];
+    readonly claim: WorkItemClaimRecord | undefined;
+    readonly reports: readonly WorkItemReportRecord[];
+    readonly dispatch: WorkItemDispatchRecord | undefined;
+}
+export interface ClaimRequest {
+    readonly itemId: string;
+    readonly runId: string;
+    readonly occurrenceId: string;
+}
+export interface ReportRequest {
+    readonly itemId: string;
+    readonly runId: string;
+    readonly status: WorkItemReportStatus;
+    readonly summary: string;
+    readonly artifactPaths: readonly string[];
+    readonly idempotencyKey: string;
+}
+/** The exact summary representation persisted by report and checked on replay. */
+export declare function normalizeWorkItemReportSummary(value: string, maxBytes: number): Readonly<{
+    summary: string;
+    truncated: boolean;
+}>;
+/**
+ * Lifecycle orchestration on top of the durable store.
+ *
+ * The ledger owns sequencing and limits (lease, attempt budget, report size,
+ * artifact containment) while the store owns atomicity. Nothing here schedules
+ * work: every transition is triggered by an admission, a tool call or startup
+ * recovery, so the plugin adds no loop or timer to the host.
+ */
+export declare class WorkItemLedger {
+    #private;
+    constructor(options: {
+        store: WorkItemStore;
+        workspace: WorkItemWorkspace;
+        limits: NormalizedLimits;
+        diagnosis?: boolean;
+        now?: () => number;
+    });
+    get store(): WorkItemStore;
+    get workspace(): WorkItemWorkspace;
+    /**
+     * Claim one item for one occurrence run.
+     *
+     * Creates the private scratch directory before the CAS so a worker never sees
+     * a claimed item without a place to write. The store decides the conflict.
+     */
+    claim(request: ClaimRequest): ClaimResult;
+    /**
+     * Park an item whose admission mandate failed revalidation.
+     *
+     * The item stays open and resumable: no claim is started, no dispatch is
+     * retired, and the same item is claimed or woken unchanged once policy allows
+     * the identical mandate again.
+     */
+    parkAuthority(item: WorkItemRecord, reason: 'authority-revoked' | 'authority-unavailable', detail?: Readonly<Record<string, unknown>>): WorkItemRecord;
+    /** Record a successful revalidation, lifting only this gate's own wait. */
+    restoreAuthority(item: WorkItemRecord): WorkItemRecord;
+    /** Mint a fresh wake after a claim-time revalidation denial left no run. */
+    rearmAuthority(item: WorkItemRecord): void;
+    /**
+     * Append a report revision under the active claim.
+     *
+     * The summary is truncated to `maxReportBytes` rather than rejected, because
+     * a long report is still evidence; artifact paths are validated strictly.
+     * Idempotent by `idempotencyKey`, so a retried tool call is safe.
+     */
+    report(request: ReportRequest): ReportResult;
+    /** Record the outcome of one delivery attempt for a report revision. */
+    recordDelivery(itemId: string, revision: number, state: WorkItemDeliveryState, deliveryId: string | null): void;
+    /** Lazy lease recovery, invoked on startup and every admission/claim. */
+    recover(): ReclaimResult;
+    detail(itemId: string): WorkItemDetail | undefined;
+    list(states?: readonly WorkItemState[], limit?: number): readonly WorkItemRecord[];
+    claimedRun(itemId: string, runId: string): WorkItemClaimRecord | undefined;
+    now(): number;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/lib/ledger.d.ts.map

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

package/lib/ledger.js

@@ -0,0 +1,145 @@
+import { truncateUtf8 } from "./config.js";
+import { WorkItemError } from "./types.js";
+function fail(code, message, detail) {
+    throw new WorkItemError(code, message, detail);
+}
+/** The exact summary representation persisted by report and checked on replay. */
+export function normalizeWorkItemReportSummary(value, maxBytes) {
+    const summary = value.trim();
+    if (summary.length === 0)
+        fail('invalid-input', 'report summary must not be empty');
+    const bounded = truncateUtf8(summary, maxBytes);
+    return Object.freeze({ summary: bounded.value, truncated: bounded.truncated });
+}
+/**
+ * Lifecycle orchestration on top of the durable store.
+ *
+ * The ledger owns sequencing and limits (lease, attempt budget, report size,
+ * artifact containment) while the store owns atomicity. Nothing here schedules
+ * work: every transition is triggered by an admission, a tool call or startup
+ * recovery, so the plugin adds no loop or timer to the host.
+ */
+export class WorkItemLedger {
+    #store;
+    #workspace;
+    #limits;
+    #now;
+    #diagnosis;
+    constructor(options) {
+        this.#store = options.store;
+        this.#workspace = options.workspace;
+        this.#limits = options.limits;
+        this.#diagnosis = options.diagnosis ?? false;
+        this.#now = options.now ?? (() => Date.now());
+    }
+    get store() {
+        return this.#store;
+    }
+    get workspace() {
+        return this.#workspace;
+    }
+    /**
+     * Claim one item for one occurrence run.
+     *
+     * Creates the private scratch directory before the CAS so a worker never sees
+     * a claimed item without a place to write. The store decides the conflict.
+     */
+    claim(request) {
+        const item = this.#store.findItemById(request.itemId);
+        if (item === undefined) {
+            const viaOccurrence = this.#store.findItemByOccurrence(request.occurrenceId);
+            if (viaOccurrence === undefined)
+                fail('not-found', 'no work item is bound to this run');
+            fail('identity-mismatch', 'reported item does not match the dispatched occurrence');
+        }
+        const directory = this.#workspace.ensureDirectory(item.id);
+        if (item.workDir !== directory) {
+            // The item was admitted before its directory existed; keep the stored
+            // path authoritative and refuse a silently relocated workspace.
+            if (!this.#workspace.contains(item.workDir))
+                fail('storage', 'stored work directory escapes workRoot');
+            this.#workspace.ensureDirectory(item.id);
+        }
+        return this.#store.claim({ itemId: item.id, runId: request.runId, occurrenceId: request.occurrenceId, leaseMs: this.#limits.leaseMs, ...(this.#diagnosis ? { reclaimExpired: false } : {}) });
+    }
+    /**
+     * Park an item whose admission mandate failed revalidation.
+     *
+     * The item stays open and resumable: no claim is started, no dispatch is
+     * retired, and the same item is claimed or woken unchanged once policy allows
+     * the identical mandate again.
+     */
+    parkAuthority(item, reason, detail = {}) {
+        return this.#store.parkAuthority(item.id, reason, detail, this.#now());
+    }
+    /** Record a successful revalidation, lifting only this gate's own wait. */
+    restoreAuthority(item) {
+        return this.#store.restoreAuthority(item.id, this.#now());
+    }
+    /** Mint a fresh wake after a claim-time revalidation denial left no run. */
+    rearmAuthority(item) {
+        this.#store.rearmAuthority(item.id);
+    }
+    /**
+     * Append a report revision under the active claim.
+     *
+     * The summary is truncated to `maxReportBytes` rather than rejected, because
+     * a long report is still evidence; artifact paths are validated strictly.
+     * Idempotent by `idempotencyKey`, so a retried tool call is safe.
+     */
+    report(request) {
+        const item = this.#store.findItemById(request.itemId);
+        if (item === undefined)
+            fail('not-found', 'work item does not exist');
+        const claim = this.#store.findClaimByRun(request.runId);
+        if (claim === undefined)
+            fail('claim-conflict', 'claim this item before reporting');
+        const bounded = normalizeWorkItemReportSummary(request.summary, this.#limits.maxReportBytes);
+        const artifacts = this.#workspace.validateArtifacts(item, request.artifactPaths);
+        return this.#store.report({
+            itemId: item.id,
+            runId: request.runId,
+            status: request.status,
+            summary: bounded.summary,
+            truncated: bounded.truncated,
+            artifactPaths: artifacts,
+            idempotencyKey: request.idempotencyKey,
+            maxReports: this.#limits.maxReportsPerItem,
+            leaseMs: this.#limits.leaseMs,
+            waitingResumeMs: this.#limits.waitingResumeMs,
+        });
+    }
+    /** Record the outcome of one delivery attempt for a report revision. */
+    recordDelivery(itemId, revision, state, deliveryId) {
+        this.#store.setReportDelivery(itemId, revision, state, deliveryId);
+    }
+    /** Lazy lease recovery, invoked on startup and every admission/claim. */
+    recover() {
+        if (this.#diagnosis)
+            return Object.freeze({ requeued: Object.freeze([]), blocked: Object.freeze([]) });
+        return this.#store.reclaimExpired();
+    }
+    detail(itemId) {
+        const item = this.#store.findItemById(itemId);
+        if (item === undefined)
+            return undefined;
+        return Object.freeze({
+            item,
+            events: this.#store.events(item.id),
+            claim: this.#store.activeClaim(item.id),
+            reports: this.#store.reports(item.id),
+            dispatch: this.#store.getDispatch(item.id),
+        });
+    }
+    list(states, limit) {
+        return this.#store.listItems({ ...(states === undefined ? {} : { states }), ...(limit === undefined ? {} : { limit }) });
+    }
+    claimedRun(itemId, runId) {
+        const claim = this.#store.findClaimByRun(runId);
+        return claim !== undefined && claim.itemId === itemId ? claim : undefined;
+    }
+    now() {
+        return this.#now();
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/lib/ledger.js.map

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

package/lib/mandate.d.ts

@@ -0,0 +1,45 @@
+import type { WorkItemAcceptanceBinding, WorkItemAcceptanceHandle, WorkItemAdmitInput, WorkItemDecisionRefusal, WorkItemExecuteDecision, WorkItemMandateBasis } from './types.ts';
+/** Normalized decision; mandate fields are re-validated by ordinary admission. */
+export interface NormalizedExecuteDecision {
+    readonly decisionId: string;
+    readonly origin: WorkItemExecuteDecision['origin'];
+    readonly mode: WorkItemExecuteDecision['mode'];
+    readonly policyRuleId: string | undefined;
+    readonly budgetRemaining: number;
+    readonly input: WorkItemAdmitInput;
+    /** Acceptance handle, resolved against the verifier by admission. */
+    readonly acceptance: WorkItemAcceptanceHandle | undefined;
+}
+/**
+ * Structural validation of one execute decision. Pure and deterministic.
+ *
+ * Only the shape is checked here; kind/title/brief/binding normalization stays
+ * with `WorkItemAdmission` so the two admission paths cannot drift.
+ */
+export declare function normalizeExecuteDecision(value: unknown): NormalizedExecuteDecision;
+/** Stable external identity: the decision id alone decides the dedup key. */
+export declare function decisionExternalId(decisionId: string): string;
+/**
+ * The inferred-execution gate. All three conditions must hold at once; an
+ * explicit decision is not gated here (Policy and ordinary admission gates
+ * still apply to it).
+ */
+export declare function decisionRefusal(decision: NormalizedExecuteDecision): WorkItemDecisionRefusal | undefined;
+/**
+ * Digest over the decision identity after admission normalized the mandate.
+ *
+ * Mode and remaining budget are admission-time facts, not identity: a replay
+ * of the same decision after the budget moved must resolve to the same item,
+ * while a different scope under the same id must not.
+ */
+export declare function mandateDigest(decision: NormalizedExecuteDecision, normalized: {
+    readonly kind: string;
+    readonly title: string;
+    readonly brief: string;
+    readonly originBindingId: string;
+    readonly acceptanceRef: string | null;
+}): string;
+export declare function buildMandateBasis(decision: NormalizedExecuteDecision, digest: string, acceptance?: WorkItemAcceptanceBinding): WorkItemMandateBasis;
+/** Structural check of a stored mandate; anything else is a malformed basis. */
+export declare function mandateIsUsable(value: unknown): value is WorkItemMandateBasis;
+//# sourceMappingURL=mandate.d.ts.map

package/lib/mandate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mandate.d.ts","sourceRoot":"","sources":["../src/mandate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,yBAAyB,EACzB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AA0BnB,kFAAkF;AAClF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;IAClC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,wBAAwB,GAAG,SAAS,CAAA;CAC1D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,CAgDlF;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,yBAAyB,GAAG,uBAAuB,GAAG,SAAS,CAMxG;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,yBAAyB,EAAE,UAAU,EAAE;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CACtC,GAAG,MAAM,CAeT;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,yBAAyB,EACnC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,yBAAyB,GACrC,oBAAoB,CAWtB;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAmB7E"}