@lssm/lib.contracts-spec 17.3.2

package/dist/operations/audit/event.list.query.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @docblock
+ * id: docs.contracts-spec.operations.audit.event.list
+ * title: audit.event.list
+ * summary: Paginated query over the immutable audit log filtered by subject, actor, category, severity, and retention window.
+ * kind: reference
+ * visibility: public
+ * route: /docs/contracts/operations/audit#event-list
+ * tags: audit, read, compliance, agent-workflow-pillar
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * `audit.event.list` — paginated query over the immutable audit log.
+ *
+ * Filters by subject / actor / category / severity / retention window.
+ * Retention-window filter is applied automatically; `includeExpired` flag
+ * bypasses it for forensic peeks (requires `audit.export` capability).
+ * Read-only — no audit event emitted per SEAMS §3.11.
+ *
+ * See `./DOMAIN_NOTES.md` §0 (append-only invariant + retention) + §1.1.
+ */
+export declare const EventListQuery: import("..").OperationSpec<SchemaModel<{
+    tenantId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Filter by subject reference, e.g. `agent:{id}`, `policy:{id}`, `workflowRun:{id}`. */
+    subjectRef: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    /** Filter by actor reference. */
+    actorRef: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    category: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+    severity: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+    /** ISO-8601 UTC start of window (inclusive). */
+    from: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: true;
+    };
+    /** ISO-8601 UTC end of window (exclusive). */
+    to: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: true;
+    };
+    retentionClass: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+        isArray: true;
+    };
+    /** Admin-only — requires `audit.export` capability. Default false. */
+    includeExpired: {
+        type: import("@lssm/lib.schema").FieldType<boolean, boolean>;
+        isOptional: true;
+    };
+    cursor: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    limit: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, SchemaModel<{
+    /** JSON-serialised AuditRecordSummary[] — SchemaModel does not nest. */
+    items: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    nextCursor: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    /** Approximate; exact count off-limits at scale. */
+    approxTotal: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: true;
+    };
+}>, undefined>;

package/dist/operations/audit/event.list.query.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{StabilityEnum as i}from"../../ownership.js";import{defineQuery as r}from"../operation.js";import{AUDIT_DOMAIN as n,AUDIT_OWNERS as a}from"./shared-schemas.js";const o=new e({name:"AuditEventListInput",fields:{tenantId:{type:t.NonEmptyString(),isOptional:!1},subjectRef:{type:t.String_unsecure(),isOptional:!0},actorRef:{type:t.String_unsecure(),isOptional:!0},category:{type:t.NonEmptyString(),isOptional:!0,isArray:!0},severity:{type:t.NonEmptyString(),isOptional:!0,isArray:!0},from:{type:t.DateTime(),isOptional:!0},to:{type:t.DateTime(),isOptional:!0},retentionClass:{type:t.NonEmptyString(),isOptional:!0,isArray:!0},includeExpired:{type:t.Boolean(),isOptional:!0},cursor:{type:t.String_unsecure(),isOptional:!0},limit:{type:t.Int_unsecure(),isOptional:!0}}});const s=new e({name:"AuditEventListOutput",fields:{items:{type:t.String_unsecure(),isOptional:!1},nextCursor:{type:t.String_unsecure(),isOptional:!0},approxTotal:{type:t.Int_unsecure(),isOptional:!0}}});export const EventListQuery=r({meta:{key:"audit.event.list",title:"List Audit Events",version:"1.0.0",description:"Paginated query over the immutable audit log filtered by subject, actor, category, severity, and retention window.",goal:"Power the audit-trail screen, compliance investigations, and operator-inbox feeds.",context:"Phase 0.4.E contract authoring. Auditor + ops + admin all read; capability `audit.read` enforced. Retention-window filter automatic; includeExpired forensic peek requires `audit.export` (Q-14 deferred to admin RBAC; v1.0 honours flag iff cap present).",domain:n,owners:[...a],tags:["audit","read","compliance","agent-workflow-pillar"],stability:i.Experimental},io:{input:o,output:s,errors:{FORBIDDEN:{description:"Caller lacks `audit.read`, requested `includeExpired` without `audit.export`, or tenant scope mismatch.",http:403,when:"Persona projection denies access or capability missing."},VALIDATION:{description:"Bad filter, cursor token, malformed date range, or limit out of range.",http:400,when:"Input rejected at validation; recoverable=false."}}},policy:{auth:"user",permissions:["audit.read"],pii:[]}});

package/dist/operations/audit/evidence.attach.command.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @docblock
+ * id: docs.contracts-spec.operations.audit.evidence.attach
+ * title: audit.evidence.attach
+ * summary: Append evidence to an existing audit event; capability resolved per caller domain via attachContext discriminator.
+ * kind: reference
+ * visibility: public
+ * route: /docs/contracts/operations/audit#evidence-attach
+ * tags: audit, write, evidence, compliance, agent-workflow-pillar
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * `audit.evidence.attach` — CROSS-DOMAIN SEAM (SEAMS S-08).
+ *
+ * Three caller domains converge here: review, governance, agent (archive),
+ * plus admin tooling and audit-system self-events. The handler resolves
+ * capability per `attachContext.kind`:
+ *   - review     → `review.act` ∨ `review.escalate`
+ *   - governance → `governance.write`
+ *   - agent      → `agent.fleet.deploy` (archive capability)
+ *   - admin      → `audit.export` + tenant-admin role
+ *   - system     → trusted-internal (no caller capability)
+ *
+ * v1.0 single-item only — batch `evidence[]` (cap 10) deferred to v1.1
+ * per SEAMS Q-09. Append-only — never modifies the parent event (DOMAIN_NOTES
+ * §0 invariant).
+ *
+ * Idempotency: `(eventId, evidenceHash, attachContext.refId, idempotencyKey)`
+ * quadruple — re-attach is a no-op success.
+ *
+ * See `../shared/attach-context.ts` for the discriminated union shape.
+ */
+export declare const EvidenceAttachCommand: import("..").OperationSpec<SchemaModel<{
+    tenantId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Parent audit event being annotated. */
+    eventId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** `attachment` | `note` | `screenshot` | `signed-statement` | `external-link`. */
+    evidenceKind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** JSON-serialised EvidencePayload — discriminated by evidenceKind. Binary content uploaded via signed-URL prior to this call. */
+    payload: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Cross-checked against the session. */
+    actorRef: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /**
+     * Discriminated `attachContext` (see `../shared/attach-context.ts`).
+     * JSON-serialised `{ kind: 'review' | 'governance' | 'agent' | 'admin' | 'system', refId?: string }`.
+     * Capability resolved per kind — SEAMS §3.8 + audit DOMAIN_NOTES §4.
+     */
+    attachContext: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Inherits from parent event if omitted. */
+    redactionPolicy: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+    idempotencyKey: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, SchemaModel<{
+    id: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    parentEventId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    kind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    hash: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    signedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: true;
+    };
+    retentionClass: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    state: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** SEAMS S-11: self-audit event recording the attachment itself. */
+    auditEventId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/operations/audit/evidence.attach.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";import{StabilityEnum as i}from"../../ownership.js";import{defineCommand as n}from"../operation.js";import{AUDIT_DOMAIN as a,AUDIT_OWNERS as o}from"./shared-schemas.js";const r=new e({name:"AuditEvidenceAttachInput",fields:{tenantId:{type:t.NonEmptyString(),isOptional:!1},eventId:{type:t.ID(),isOptional:!1},evidenceKind:{type:t.NonEmptyString(),isOptional:!1},payload:{type:t.String_unsecure(),isOptional:!1},actorRef:{type:t.NonEmptyString(),isOptional:!1},attachContext:{type:t.String_unsecure(),isOptional:!1},redactionPolicy:{type:t.NonEmptyString(),isOptional:!0},idempotencyKey:{type:t.ID(),isOptional:!1}}});const p=new e({name:"AuditEvidenceAttachOutput",fields:{id:{type:t.ID(),isOptional:!1},parentEventId:{type:t.ID(),isOptional:!1},kind:{type:t.NonEmptyString(),isOptional:!1},hash:{type:t.NonEmptyString(),isOptional:!1},signedAt:{type:t.DateTime(),isOptional:!0},retentionClass:{type:t.NonEmptyString(),isOptional:!1},state:{type:t.NonEmptyString(),isOptional:!1},auditEventId:{type:t.ID(),isOptional:!1}}});export const EvidenceAttachCommand=n({meta:{key:"audit.evidence.attach",title:"Attach Evidence to Audit Event",version:"1.0.0",description:"Append evidence to an existing audit event; capability resolved per caller domain via attachContext discriminator.",goal:"Let review/governance/agent/admin/system callers attach justification or proof artefacts to an immutable audit record.",context:"Phase 0.4.E contract authoring. SEAMS S-08 (3 caller domains converge) + Q-09 (single-item v1.0). Append-only \u2014 parent event never mutates.",domain:a,owners:[...o],tags:["audit","write","evidence","compliance","agent-workflow-pillar"],stability:i.Experimental},io:{input:r,output:p,errors:{NOT_FOUND:{description:"Parent event id does not exist in this tenant scope.",http:404,when:"No audit record matches (tenantId, eventId)."},CONFLICT:{description:"Duplicate attach with same idempotencyKey + evidenceHash.",http:409,when:"Idempotent replay returns the existing record; differing hash \u2192 CONFLICT."},FORBIDDEN:{description:"attachContext.kind does not match the caller domain, or caller lacks the capability for that kind.",http:403,when:"Capability gate per SEAMS \xA73.8 matrix; auditor \u2192 typically FORBIDDEN unless explicitly granted attach scope."},VALIDATION:{description:"Payload shape mismatch with evidenceKind, malformed attachContext, or unknown evidenceKind.",http:400,when:"Input rejected at validation; recoverable=false."},DEPENDENCY:{description:"Blob upload missing or scan service down.",http:503,when:"Underlying adapter transient; recoverable=true."},IDEMPOTENCY_FAIL:{description:"idempotencyKey collision with differing payload.",http:409,when:"Same key reused with differing context; recoverable=false."}}},policy:{auth:"user",permissions:["audit.read"],pii:[]}});

package/dist/operations/audit/pipeline.health.query.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @docblock
+ * id: docs.contracts-spec.operations.audit.pipeline.health
+ * title: audit.pipeline.health
+ * summary: Health probe for the audit ingestion + retention pipeline; consumed by fleet.health.snapshot.
+ * kind: reference
+ * visibility: public
+ * route: /docs/contracts/operations/audit#pipeline-health
+ * tags: audit, read, health, agent-workflow-pillar
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * `audit.pipeline.health` — health probe consumed by `fleet.health.snapshot`.
+ *
+ * SEAMS Q-05 + S-10: fleet aggregates this with `agent.fleet.health`,
+ * `workflow.runner.health`, `review.queue.health`, `governance.policy.health`.
+ * Missing probe ⇒ component reported as `amber` with `symptoms:
+ * ['health-probe-not-available']`. Probe MUST be cheap (target p95 <100ms).
+ */
+export declare const PipelineHealthQuery: import("..").OperationSpec<SchemaModel<{
+    tenantId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, SchemaModel<{
+    /** `green` | `amber` | `red` — composed by `fleet.health.snapshot`. */
+    status: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Ingestion lag p95 in milliseconds — write-to-queryable latency. */
+    ingestionLagMsP95: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: false;
+    };
+    /** Count of records pending scan (PENDING_SCAN evidence state). */
+    pendingScanEvidence: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: false;
+    };
+    /** Count of quarantined evidence items (manual release required). */
+    quarantinedEvidence: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: false;
+    };
+    /** Count of retention-purges scheduled (ephemeral records past TTL). */
+    retentionPurgesPending: {
+        type: import("@lssm/lib.schema").FieldType<number, number>;
+        isOptional: false;
+    };
+    /** ISO timestamp of last successful audit-event append. */
+    lastEventAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: true;
+    };
+    /** JSON-serialised string[] of qualitative symptom labels. */
+    symptoms: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Probe timestamp (server clock). */
+    probedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/operations/audit/pipeline.health.query.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{StabilityEnum as i}from"../../ownership.js";import{defineQuery as n}from"../operation.js";import{AUDIT_DOMAIN as a,AUDIT_OWNERS as l}from"./shared-schemas.js";const r=new t({name:"AuditPipelineHealthInput",fields:{tenantId:{type:e.NonEmptyString(),isOptional:!1}}});const o=new t({name:"AuditPipelineHealthOutput",fields:{status:{type:e.NonEmptyString(),isOptional:!1},ingestionLagMsP95:{type:e.Int_unsecure(),isOptional:!1},pendingScanEvidence:{type:e.Int_unsecure(),isOptional:!1},quarantinedEvidence:{type:e.Int_unsecure(),isOptional:!1},retentionPurgesPending:{type:e.Int_unsecure(),isOptional:!1},lastEventAt:{type:e.DateTime(),isOptional:!0},symptoms:{type:e.String_unsecure(),isOptional:!1},probedAt:{type:e.DateTime(),isOptional:!1}}});export const PipelineHealthQuery=n({meta:{key:"audit.pipeline.health",title:"Audit Pipeline Health Probe",version:"1.0.0",description:"Health probe for the audit ingestion + retention pipeline; consumed by fleet.health.snapshot.",goal:"Surface audit pipeline state into the operating cockpit fleet health view.",context:"Phase 0.4.E contract authoring. SEAMS Q-05 + S-10 \u2014 owned by W5. Probe is cheap; full forensic data lives on event.list / event.get.",domain:a,owners:[...l],tags:["audit","read","health","agent-workflow-pillar"],stability:i.Experimental},capability:{key:"fleet.metrics.read",version:"1.0.0"},io:{input:r,output:o,errors:{FORBIDDEN:{description:"Caller lacks `audit.read` OR `fleet.metrics.read` capability.",http:403,when:"Persona projection denies access (auditor + ops + admin all allowed)."},DEPENDENCY:{description:"Audit store unavailable; probe cannot complete.",http:503,when:"Underlying store transient; recoverable=true. Fleet renders amber."}}},policy:{auth:"user",permissions:["audit.read","fleet.metrics.read"],pii:[]}});

package/dist/operations/audit/shared-schemas.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared SchemaModel building blocks for the audit domain (Phase 0.4.E).
+ *
+ * Centralises tenant + audit-record + evidence shapes so each contract file
+ * stays at-a-glance reviewable. See `./DOMAIN_NOTES.md` for the append-only
+ * invariant, retention table, and capability-by-caller matrix, and
+ * `../SEAMS.md` for S-08 (evidence.attach), S-11 (audit-event-on-mutation).
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+export declare const AUDIT_DOMAIN = "audit";
+export declare const AUDIT_OWNERS: readonly ['@platform.audit'];
+/** Retention classes — see `./DOMAIN_NOTES.md` §0. */
+export declare const RETENTION_CLASSES: readonly ['regulatory', 'operational', 'ephemeral'];
+export type RetentionClass = (typeof RETENTION_CLASSES)[number];
+/** Audit categories — see `./DOMAIN_NOTES.md` §1.1 list filter. */
+export declare const AUDIT_CATEGORIES: readonly ['governance', 'review', 'agent', 'workflow', 'fleet', 'auth', 'audit'];
+export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
+/** Audit-event severity levels. */
+export declare const AUDIT_SEVERITIES: readonly ['info', 'notice', 'warning', 'critical'];
+export type AuditSeverity = (typeof AUDIT_SEVERITIES)[number];
+/** Evidence-attachment kinds — `audit.evidence.attach` discriminator. */
+export declare const EVIDENCE_KINDS: readonly ['attachment', 'note', 'screenshot', 'signed-statement', 'external-link'];
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+/** Evidence lifecycle states — see `./DOMAIN_NOTES.md` §2.1. */
+export declare const EVIDENCE_STATES: readonly ['PENDING_SCAN', 'AVAILABLE', 'QUARANTINED', 'PURGED'];
+export type EvidenceState = (typeof EVIDENCE_STATES)[number];
+/** Audit-event-export output format. */
+export declare const EXPORT_FORMATS: readonly ['jsonl', 'csv', 'parquet'];
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+/** Audit-export signing modes. `none` forbidden for regulatory class. */
+export declare const EXPORT_SIGNINGS: readonly ['pkcs7', 'cosign', 'none'];
+export type ExportSigning = (typeof EXPORT_SIGNINGS)[number];
+/** Tenant-scoped audit input. */
+export declare const AuditTenantScopeInput: SchemaModel<{
+    tenantId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>;
+/** Audit-record summary row surfaced by `audit.event.list`. */
+export declare const AuditRecordSummaryModel: SchemaModel<{
+    id: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    occurredAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    actor: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    subject: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    category: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    severity: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    retentionClass: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>;
+/** Evidence-record summary row surfaced by `audit.event.get`. */
+export declare const EvidenceRecordModel: SchemaModel<{
+    id: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    parentEventId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    kind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    /** Content hash (sha256) — stable across replays. */
+    hash: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    signedAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: true;
+    };
+    retentionClass: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    state: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>;

package/dist/operations/audit/shared-schemas.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as e}from"@lssm/lib.schema";export const AUDIT_DOMAIN="audit";export const AUDIT_OWNERS=["@platform.audit"];export const RETENTION_CLASSES=["regulatory","operational","ephemeral"];export const AUDIT_CATEGORIES=["governance","review","agent","workflow","fleet","auth","audit"];export const AUDIT_SEVERITIES=["info","notice","warning","critical"];export const EVIDENCE_KINDS=["attachment","note","screenshot","signed-statement","external-link"];export const EVIDENCE_STATES=["PENDING_SCAN","AVAILABLE","QUARANTINED","PURGED"];export const EXPORT_FORMATS=["jsonl","csv","parquet"];export const EXPORT_SIGNINGS=["pkcs7","cosign","none"];export const AuditTenantScopeInput=new e({name:"AuditTenantScopeInput",fields:{tenantId:{type:t.NonEmptyString(),isOptional:!1}}});export const AuditRecordSummaryModel=new e({name:"AuditRecordSummaryRow",fields:{id:{type:t.ID(),isOptional:!1},occurredAt:{type:t.DateTime(),isOptional:!1},actor:{type:t.NonEmptyString(),isOptional:!1},subject:{type:t.NonEmptyString(),isOptional:!1},category:{type:t.NonEmptyString(),isOptional:!1},severity:{type:t.NonEmptyString(),isOptional:!1},retentionClass:{type:t.NonEmptyString(),isOptional:!1}}});export const EvidenceRecordModel=new e({name:"EvidenceRecord",fields:{id:{type:t.ID(),isOptional:!1},parentEventId:{type:t.ID(),isOptional:!1},kind:{type:t.NonEmptyString(),isOptional:!1},hash:{type:t.NonEmptyString(),isOptional:!1},signedAt:{type:t.DateTime(),isOptional:!0},retentionClass:{type:t.NonEmptyString(),isOptional:!1},state:{type:t.NonEmptyString(),isOptional:!1}}});

package/dist/operations/ceremony-authority.d.ts

@@ -0,0 +1,50 @@
+import type { OperationApprovalSubject, OperationCeremonyCompletion, OperationCeremonyDecision, OperationCeremonyPort, OperationCeremonyReceipt, OperationCeremonyRequest } from './approval.js';
+export interface TrustedOperationCeremonyRecord {
+    receipt: OperationCeremonyReceipt;
+    subject: OperationApprovalSubject;
+}
+/** Host-owned signature verifier or server-side challenge lookup. */
+export interface OperationCeremonyReceiptVerifier {
+    verify(receipt: OperationCeremonyReceipt): Promise<TrustedOperationCeremonyRecord | null>;
+}
+export interface OperationCeremonyClaimStore {
+    claim(input: {
+        nonce: string;
+        ceremonyId: string;
+        maxAttempts: number;
+    }): Promise<{
+        claimed: true;
+        leaseId: string;
+    } | {
+        claimed: false;
+    }>;
+    complete(completion: OperationCeremonyCompletion): Promise<void>;
+}
+export declare class ReferenceOperationCeremonyPort implements OperationCeremonyPort {
+    private readonly options;
+    constructor(options: {
+        host: string;
+        store: OperationCeremonyClaimStore;
+        verifier: OperationCeremonyReceiptVerifier;
+        clock?: () => Date;
+        maxAttempts?: number;
+    });
+    claim(request: OperationCeremonyRequest): Promise<OperationCeremonyDecision>;
+    complete(completion: OperationCeremonyCompletion): Promise<void>;
+}
+/** Test/reference store. Production hosts must replace this with a durable store. */
+export declare class MemoryOperationCeremonyClaimStore implements OperationCeremonyClaimStore {
+    private readonly states;
+    private readonly nonceByLease;
+    claim(input: {
+        nonce: string;
+        ceremonyId: string;
+        maxAttempts: number;
+    }): Promise<{
+        claimed: true;
+        leaseId: string;
+    } | {
+        claimed: false;
+    }>;
+    complete(completion: OperationCeremonyCompletion): Promise<void>;
+}

package/dist/operations/ceremony-authority.js

@@ -0,0 +1 @@
+export class ReferenceOperationCeremonyPort{options;constructor(t){this.options=t}async claim(t){const e=t.receipt,n=await this.options.verifier.verify(e);if(!n)return{effect:"deny",reason:"unknown_ceremony"};if(!s(e,n.receipt))return{effect:"deny",reason:"forged_ceremony"};if(!c(t.subject,n.subject))return{effect:"deny",reason:"wrong_subject"};const o=(this.options.clock??(()=>new Date))().getTime(),r=Date.parse(e.issuedAt),i=Date.parse(e.expiresAt);if(!Number.isFinite(r)||!Number.isFinite(i))return{effect:"deny",reason:"malformed_ceremony"};if(r>o)return{effect:"deny",reason:"not_yet_valid"};if(i<=o)return{effect:"deny",reason:"expired_ceremony"};if(e.host!==this.options.host)return{effect:"deny",reason:"wrong_host"};if(e.kind!==t.requirement.kind)return{effect:"deny",reason:"wrong_kind"};if(e.operation.key!==t.operation.key||e.operation.version!==t.operation.version)return{effect:"deny",reason:"wrong_operation"};const a=await this.options.store.claim({nonce:e.nonce,ceremonyId:e.id,maxAttempts:this.options.maxAttempts??3});return a.claimed?{effect:"allow",ceremonyId:e.id,leaseId:a.leaseId}:{effect:"deny",reason:"replayed_ceremony"}}complete(t){return this.options.store.complete(t)}}export class MemoryOperationCeremonyClaimStore{states=new Map;nonceByLease=new Map;async claim(t){const e=this.states.get(t.nonce)??{attempts:0,state:"available"};if(e.state!=="available"||e.attempts>=t.maxAttempts)return{claimed:!1};const n=`${t.ceremonyId}:${e.attempts+1}`;this.states.set(t.nonce,{attempts:e.attempts+1,state:"claimed",leaseId:n});this.nonceByLease.set(n,t.nonce);return{claimed:!0,leaseId:n}}async complete(t){const e=this.nonceByLease.get(t.leaseId);if(!e)throw Error("Unknown ceremony completion lease.");const n=this.states.get(e);if(!n||n.leaseId!==t.leaseId)throw Error("Stale ceremony completion lease.");this.states.set(e,{attempts:n.attempts,state:t.outcome==="succeeded"?"consumed":"available"});this.nonceByLease.delete(t.leaseId)}}function s(t,e){return t.id===e.id&&t.kind===e.kind&&t.host===e.host&&t.issuedAt===e.issuedAt&&t.expiresAt===e.expiresAt&&t.nonce===e.nonce&&t.operation.key===e.operation.key&&t.operation.version===e.operation.version}function c(t,e){return(t.actor??null)===(e.actor??null)&&(t.userId??null)===(e.userId??null)&&(t.tenantId??null)===(e.tenantId??null)&&(t.workspaceId??null)===(e.workspaceId??null)&&(t.organizationId??null)===(e.organizationId??null)&&(t.ceremonyBindingRef??null)===(e.ceremonyBindingRef??null)}

package/dist/operations/coach/agent-suggest-tool.command.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @docblock
+ * id: docs.contracts-spec.operations.coach.agent-suggest-tool
+ * title: agent.coach.suggest-tool
+ * summary: Suggest tools to assign to an agent based on context.
+ * kind: reference
+ * visibility: internal
+ * route: /docs/contracts/operations/coach#agent-suggest-tool
+ * tags: coach, agent, suggest, intelligence, agent-workflow-pillar
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * Suggest tools to attach to an agent. Read-modifying — emits a
+ * `coach_suggestion_offered` telemetry event so adaptive-recipes (#67)
+ * can correlate offered → accepted via `suggestionTraceId`.
+ *
+ * Caller passes optional `context` (free-form hint from the UI) and
+ * `limit` (default 3, max 10 — handler-enforced). Handler delegates
+ * inference to `lib.ai-agent` and returns ranked rows.
+ */
+export declare const AgentCoachSuggestToolCommand: import("..").OperationSpec<SchemaModel<{
+    tenantId: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: false;
+    };
+    workspaceId: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: true;
+    };
+    context: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: true;
+    };
+    limit: {
+        readonly type: import("@lssm/lib.schema").FieldType<number, number>;
+        readonly isOptional: true;
+    };
+    length: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: true;
+    };
+    agentId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>, SchemaModel<{
+    suggestionTraceId: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: false;
+    };
+    suggestions: {
+        type: import("@lssm/lib.schema").FieldType<unknown, unknown>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/operations/coach/agent-suggest-tool.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{StabilityEnum as o}from"../../ownership.js";import{defineCommand as a}from"../operation.js";import{COACH_DOMAIN as n,COACH_OWNERS as s,COACH_TAGS as i,CoachContextFields as g,CoachErrors as c,CoachScopeFields as r,CoachTrackingFields as l}from"./shared-schemas.js";const u=new t({name:"AgentCoachSuggestToolInput",fields:{...r,agentId:{type:e.String_unsecure(),isOptional:!1},...g}});const p=new t({name:"AgentCoachSuggestToolOutput",fields:{...l,suggestions:{type:e.JSON(),isOptional:!1}}});export const AgentCoachSuggestToolCommand=a({meta:{key:"agent.coach.suggest-tool",title:"Coach \u2014 Suggest Agent Tools",version:"1.0.0",description:"Suggest tools to attach to an agent. Returns up to N ranked candidates with rationale + confidence.",goal:"Help operators discover the right tool bindings without scanning the full tool registry.",context:'Phase 6.A coach command. Read-modifying (telemetry side-effect). Inference provided by lib.ai-agent per plan \xA7"Phase 6 \u2014 Intelligence layer". Capability gate: coach.suggest.',domain:n,owners:[...s],tags:[...i,"agent","tool","suggest"],stability:o.Experimental},io:{input:u,output:p,errors:{...c}},policy:{auth:"user",permissions:["coach.suggest"],pii:[]},sideEffects:{audit:["coach.suggestion.offered"]}});

package/dist/operations/coach/governance-suggest-constraint.command.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @docblock
+ * id: docs.contracts-spec.operations.coach.governance-suggest-constraint
+ * title: governance.coach.suggest-constraint
+ * summary: Suggest additional constraints for a draft policy delta.
+ * kind: reference
+ * visibility: internal
+ * route: /docs/contracts/operations/coach#governance-suggest-constraint
+ * tags: coach, governance, suggest, intelligence, agent-workflow-pillar
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * Suggest additional constraints to add to a policy draft. Read-modifying
+ * — emits `coach.suggestion.offered`.
+ *
+ * Operates on a *draft* policy delta (not the active policy) so callers
+ * can iterate before triggering `governance.policy.simulate` /
+ * `governance.policy.update`. Capability gate: `coach.suggest`.
+ *
+ * Auditor sees the suggestions in read-only mode — the surrounding
+ * "Add to policy" affordance stays `disabled` per SEAMS.md §1.5.
+ */
+export declare const GovernanceCoachSuggestConstraintCommand: import("..").OperationSpec<SchemaModel<{
+    tenantId: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: false;
+    };
+    workspaceId: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: true;
+    };
+    context: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: true;
+    };
+    limit: {
+        readonly type: import("@lssm/lib.schema").FieldType<number, number>;
+        readonly isOptional: true;
+    };
+    length: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: true;
+    };
+    policyId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    draftDelta: {
+        type: import("@lssm/lib.schema").FieldType<unknown, unknown>;
+        isOptional: false;
+    };
+}>, SchemaModel<{
+    suggestionTraceId: {
+        readonly type: import("@lssm/lib.schema").FieldType<string, string>;
+        readonly isOptional: false;
+    };
+    suggestions: {
+        type: import("@lssm/lib.schema").FieldType<unknown, unknown>;
+        isOptional: false;
+    };
+}>, undefined>;

package/dist/operations/coach/governance-suggest-constraint.command.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";import{StabilityEnum as o}from"../../ownership.js";import{defineCommand as n}from"../operation.js";import{COACH_DOMAIN as a,COACH_OWNERS as i,COACH_TAGS as s,CoachContextFields as c,CoachErrors as r,CoachScopeFields as g,CoachTrackingFields as d}from"./shared-schemas.js";const l=new t({name:"GovernanceCoachSuggestConstraintInput",fields:{...g,policyId:{type:e.String_unsecure(),isOptional:!1},draftDelta:{type:e.JSON(),isOptional:!1},...c}});const p=new t({name:"GovernanceCoachSuggestConstraintOutput",fields:{...d,suggestions:{type:e.JSON(),isOptional:!1}}});export const GovernanceCoachSuggestConstraintCommand=n({meta:{key:"governance.coach.suggest-constraint",title:"Coach \u2014 Suggest Policy Constraint",version:"1.0.0",description:"Suggest additional constraints to add to a draft policy delta, ranked by confidence and severity.",goal:"Help policy authors avoid blind spots when extending governance constraints.",context:"Phase 6.A coach command. Read-modifying (telemetry side-effect). Inference by lib.ai-agent. Capability gate: coach.suggest. Operates on draft deltas, not active policies; no governance.policy.update side-effect here.",domain:a,owners:[...i],tags:[...s,"governance","constraint","suggest"],stability:o.Experimental},io:{input:l,output:p,errors:{...r}},policy:{auth:"user",permissions:["coach.suggest"],pii:[]},sideEffects:{audit:["coach.suggestion.offered"]}});