@lssm/lib.contracts-spec 17.3.2

package/dist/shared/attach-context.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `AttachContext` — discriminated union for `audit.evidence.attach` callers.
+ *
+ * Phase 0.3.G shape promotion (SEAMS.md §4, Q-08). Used by S-08
+ * (`audit.evidence.attach` — 3 caller domains converge). The discriminator
+ * lets the audit handler short-circuit the capability check by `kind`
+ * without ambiguously resolving the caller-domain from the auth context
+ * (which is ambiguous when reviews dispatch to multiple downstream domains).
+ *
+ * Caller / capability matrix (per SEAMS.md §3.8):
+ *
+ *  | kind         | refId                | Required capability                                 |
+ *  | ------------ | -------------------- | --------------------------------------------------- |
+ *  | 'review'     | reviewId             | `review.act` ∨ `review.escalate`                    |
+ *  | 'governance' | policyId             | `governance.write`                                  |
+ *  | 'agent'      | agentId              | `agent.fleet.deploy` (archive capability)           |
+ *  | 'admin'      | undefined            | `audit.export` + tenant-admin role                  |
+ *  | 'system'     | emitterEventId       | system-only (no caller capability)                  |
+ *
+ * Design contract:
+ *  - The `kind` MUST match the calling domain. Mismatch → `FORBIDDEN`
+ *    (audit handler does not infer caller from auth context).
+ *  - `refId` is optional for `kind: 'admin'` only; required for all others.
+ *  - The audit handler attaches the resolved `attachContext` into the
+ *    emitted `audit.evidence.attached` event so downstream auditors can
+ *    trace which caller-domain attached which evidence.
+ *
+ * @see ./window.ts — sibling primitive
+ * @see ./audit.ts — sibling primitive
+ * @see ./idempotency.ts — sibling primitive
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+export type AttachContextKind = 'review' | 'governance' | 'agent' | 'admin' | 'system';
+export declare const ATTACH_CONTEXT_KINDS: readonly AttachContextKind[];
+/**
+ * Caller-context discriminator for `audit.evidence.attach`.
+ *
+ * Discriminated by `kind`. Phase 0.4 audit op authors model this as a
+ * `SchemaModel` with a `kind` enum field + an `refId` field; downstream
+ * narrowing happens handler-side via the predicates below.
+ */
+export type AttachContext = {
+    kind: 'review';
+    refId: string;
+} | {
+    kind: 'governance';
+    refId: string;
+} | {
+    kind: 'agent';
+    refId: string;
+} | {
+    kind: 'admin';
+    refId?: string;
+} | {
+    kind: 'system';
+    refId: string;
+};
+/**
+ * SchemaModel for `AttachContext`. Phase 0.4 authors of
+ * `audit.evidence.attach` reference these field shapes inside their
+ * `io.input` schema; `kind` is constrained to `ATTACH_CONTEXT_KINDS` via
+ * handler-side `validateAttachContext()`.
+ */
+export declare const AttachContextSchema: SchemaModel<{
+    kind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    refId: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: true;
+    };
+}>;
+/** Runtime predicate for `AttachContext.kind`. */
+export declare function isAttachContextKind(value: unknown): value is AttachContextKind;
+/**
+ * Validate shape + `refId` requirement per `kind`. Returns an error message
+ * on failure, `null` on success.
+ *
+ * Per §3.8: `refId` is required for `review`, `governance`, `agent`,
+ * `system`; optional for `admin`.
+ */
+export declare function validateAttachContext(value: AttachContext): string | null;

package/dist/shared/attach-context.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as n,SchemaModel as e}from"@lssm/lib.schema";export const ATTACH_CONTEXT_KINDS=["review","governance","agent","admin","system"];export const AttachContextSchema=new e({name:"AttachContext",fields:{kind:{type:n.NonEmptyString(),isOptional:!1},refId:{type:n.String_unsecure(),isOptional:!0}}});export function isAttachContextKind(t){return typeof t==="string"&&ATTACH_CONTEXT_KINDS.includes(t)}export function validateAttachContext(t){if(!isAttachContextKind(t.kind))return`AttachContext.kind must be one of ${ATTACH_CONTEXT_KINDS.join(", ")}; got "${t.kind}".`;if(t.kind!=="admin"&&(!t.refId||t.refId.length===0))return`AttachContext.refId is required when kind is "${t.kind}".`;return null}

package/dist/shared/audit.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `AuditEventId` + `AuditRecordSummary` — canonical audit reference shapes.
+ *
+ * Phase 0.3.G shape promotion (SEAMS.md §4, Q-08). Used by every mutation
+ * across all 5 mutating domains (agent, workflow, review, governance, audit
+ * itself) per S-11 (audit-event-on-mutation). The returned `auditEventId`
+ * flows back into the caller's response payload so traceability is
+ * preserved across the seam.
+ *
+ * Design contract (per audit DOMAIN_NOTES §0 append-only invariant):
+ *  - `AuditEventId` is an **opaque** UUID. Callers MUST NOT parse it for
+ *    embedded data (no timestamp extraction, no shard inference). Treat as
+ *    an identifier-only.
+ *  - `AuditRecordSummary` is the minimal reference shape — id, kind,
+ *    retention class, and occurredAt. Full record bodies require a
+ *    `audit.event.get` query (gated by `audit.read` capability).
+ *  - Retention class is decided at write-time by the emitting domain and
+ *    is **immutable** post-commit. Re-classification requires a new event
+ *    (the audit log is append-only).
+ *
+ * Phase 0.4 authors:
+ *  - Every mutating op's `io.output` SchemaModel MUST include
+ *    `auditEventId: ScalarTypeEnum.ID()` (per S-11). `lib.schema` does not
+ *    expose a dedicated UUID scalar; `ID()` is the canonical opaque
+ *    string-identifier scalar.
+ *  - Read-only ops (queries / aggregations) MUST NOT include `auditEventId`
+ *    — the read isn't audited per §3.11.
+ *
+ * @see ./window.ts — sibling primitive
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/**
+ * Retention class — see audit DOMAIN_NOTES §0 retention table.
+ *  - `regulatory`: governance.*, review.* decisions, agent.archive,
+ *    workflow.run.cancel, agent.set-autonomy, agent.set-risk-tier
+ *    (raising), agent.assign-tool when riskTier >= elevated, all S-09
+ *    system events, audit.event.export.
+ *  - `operational`: routine agent.*, workflow.*, review.assign,
+ *    review.comment.
+ *  - `ephemeral`: debug-only paths; reserved — none in v1.0.
+ */
+export type AuditRetentionClass = 'regulatory' | 'operational' | 'ephemeral';
+export declare const AUDIT_RETENTION_CLASSES: readonly AuditRetentionClass[];
+/**
+ * Opaque audit-event identifier. UUID v4 in v1.0; treat as identifier-only.
+ * Use the scalar `ScalarTypeEnum.ID()` directly when authoring a
+ * SchemaModel field — this type alias documents intent. `lib.schema` does
+ * not expose a dedicated UUID scalar; `ID()` is the canonical opaque
+ * string-identifier scalar.
+ */
+export type AuditEventId = string;
+/**
+ * Minimal reference-link shape for an audit record. Phase 0.4 authors
+ * MAY embed this in an op's response when the caller benefits from
+ * lightweight audit-trail navigation without a follow-up `audit.event.get`
+ * (e.g., `review.escalate` returning the immediate escalation event so the
+ * UI can deep-link to it).
+ */
+export interface AuditRecordSummary {
+    id: AuditEventId;
+    eventKind: string;
+    retentionClass: AuditRetentionClass;
+    /** ISO-8601 UTC timestamp at which the audit row committed. */
+    occurredAt: string;
+}
+/**
+ * SchemaModel for `AuditRecordSummary`. Phase 0.4 authors who want the
+ * embedded reference shape can copy these fields into their response
+ * SchemaModel under e.g. `auditEvent: AuditRecordSummarySchema fields`.
+ *
+ * Most ops will simply expose `auditEventId: ScalarTypeEnum.UUID()` as a
+ * single field; embedding the full summary is opt-in.
+ */
+export declare const AuditRecordSummarySchema: SchemaModel<{
+    id: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    eventKind: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    retentionClass: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+    occurredAt: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+}>;
+/** Runtime predicate for `AuditRetentionClass` — handler-side narrowing. */
+export declare function isAuditRetentionClass(value: unknown): value is AuditRetentionClass;

package/dist/shared/audit.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as n}from"@lssm/lib.schema";export const AUDIT_RETENTION_CLASSES=["regulatory","operational","ephemeral"];export const AuditRecordSummarySchema=new n({name:"AuditRecordSummary",fields:{id:{type:t.ID(),isOptional:!1},eventKind:{type:t.NonEmptyString(),isOptional:!1},retentionClass:{type:t.NonEmptyString(),isOptional:!1},occurredAt:{type:t.DateTime(),isOptional:!1}}});export function isAuditRetentionClass(e){return typeof e==="string"&&AUDIT_RETENTION_CLASSES.includes(e)}

package/dist/shared/idempotency-shape.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser-safe shape primitives for idempotency keys.
+ *
+ * Phase 0.3.G shape promotion (SEAMS.md §4, Q-08). Browser surface — must
+ * NOT import `node:crypto` or any Node-only runtime. The deterministic
+ * UUID-v5 helper that consumes these shapes lives in the Node-only sibling
+ * `./idempotency.ts` and is reachable via the explicit
+ * `@lssm/lib.contracts-spec/shared/idempotency` subpath. This mirrors
+ * the `rich-reference/denial-token-shape.ts` ↔ `denial-token.ts` split,
+ * enforced by the root browser-surface test (`index.browser-surface.test.ts`).
+ *
+ * Phase 0.4 authors importing from `@lssm/lib.contracts-spec/shared`
+ * get every browser-safe symbol below; Phase 2 handlers + the outbox
+ * adapter (#34) import `deriveIdempotencyKey` from the Node subpath.
+ *
+ * @see ./idempotency.ts — Node-only helper (`deriveIdempotencyKey`)
+ */
+/**
+ * Maximum length for a caller-supplied `IdempotencyKey`. 128 chars is large
+ * enough for any reasonable opaque identifier (UUID, ULID, base64-encoded
+ * request ID) and small enough that store-side indexes stay cheap.
+ */
+export declare const IDEMPOTENCY_KEY_MAX_LENGTH: 128;
+/**
+ * Opaque idempotency key (caller-supplied). Treat as an identifier-only
+ * string. Use `ScalarTypeEnum.String_unsecure()` with a length cap in your
+ * `io.input` SchemaModel — the `_unsecure` suffix acknowledges that the
+ * value is opaque and we do not sanitize it.
+ */
+export type IdempotencyKey = string;
+/**
+ * Validate a caller-supplied `IdempotencyKey`. Returns an error message on
+ * failure, `null` on success. Phase 0.4 authors SHOULD call this from
+ * inside their handler before reaching the dedupe store.
+ *
+ * Stricter than the SchemaModel-level length cap so handlers get a
+ * structured error code (`VALIDATION`) instead of a Zod parse failure.
+ */
+export declare function validateIdempotencyKey(value: unknown): string | null;
+/**
+ * Project-scoped namespace UUID for the agent-workflow pillar.
+ *
+ * Hard-coded as a string literal so this file stays browser-safe (no
+ * crypto import). The value is deterministic — it is itself UUID v5 of
+ * `(DNS_NAMESPACE_UUID, 'agent-workflow-pillar.contracts-spec.lssm-tech')`.
+ * The Node-only sibling test (`./shared.test.ts`) reproduces the derivation
+ * at test time so an accidental edit here surfaces immediately.
+ *
+ * Use this as the first argument to `deriveIdempotencyKey()` for any
+ * pillar-domain seam. Other namespaces MAY be introduced for non-pillar
+ * shared seams; keep them stable and documented.
+ */
+export declare const IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR: 'fcc6a2c5-0f9d-55f8-a711-2666a129bdee';
+/**
+ * SchemaModel-friendly scalar declaration. Phase 0.4 authors should write:
+ *   `idempotencyKey: { type: IdempotencyKeyScalar, isOptional: true }`
+ * to keep the field semantics uniform across every command.
+ *
+ * Note: `ScalarTypeEnum.String_unsecure()` is used because the key is
+ * caller-controlled opaque data; we do not enforce a charset, only a
+ * length cap (handler-side via `validateIdempotencyKey`).
+ */
+export declare const IdempotencyKeyScalar: import("@lssm/lib.schema").FieldType<string, string>;

package/dist/shared/idempotency-shape.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t}from"@lssm/lib.schema";export const IDEMPOTENCY_KEY_MAX_LENGTH=128;export function validateIdempotencyKey(e){if(typeof e!=="string")return"IdempotencyKey must be a string.";if(e.length===0)return"IdempotencyKey must not be empty.";if(e.length>IDEMPOTENCY_KEY_MAX_LENGTH)return`IdempotencyKey must be \u2264${IDEMPOTENCY_KEY_MAX_LENGTH} characters (got ${e.length}).`;return null}export const IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR="fcc6a2c5-0f9d-55f8-a711-2666a129bdee";export const IdempotencyKeyScalar=t.String_unsecure();

package/dist/shared/idempotency.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `deriveIdempotencyKey()` — Node-only UUID v5 derivation (RFC 4122).
+ *
+ * Phase 0.3.G shape promotion (SEAMS.md §4, Q-08). This file imports
+ * `node:crypto` and is therefore **NOT browser-safe**. It is NOT re-exported
+ * by the root `lib.contracts-spec` barrel; consumers reach it via the
+ * explicit `@lssm/lib.contracts-spec/shared/idempotency` subpath.
+ * Allow-listed in the root browser-surface test
+ * (`index.browser-surface.test.ts`), mirroring the
+ * `rich-reference/denial-token.ts` Node-only pattern.
+ *
+ * For browser-safe primitives (types, validators, scalar, namespace
+ * constant) import from `./idempotency-shape` or the root `shared` barrel.
+ *
+ * Outbox-derived downstream calls (S-02 workflow → agent.start, S-03
+ * workflow cancel → agent.stop, S-06 review.escalate → audit + governance,
+ * S-07 review.approve → 3 callees) MUST use this helper to derive their
+ * idempotency key from `(outerKey, calleeDomain, calleeOp, ...subjectIds)`
+ * so replays converge. Re-running the same caller op produces the same
+ * downstream keys → downstream callees are no-op idempotent on replay.
+ *
+ * @example
+ * ```ts
+ * // workflow.run.dispatch → agent.start (S-02)
+ * import {
+ *   deriveIdempotencyKey,
+ *   IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR,
+ * } from '@lssm/lib.contracts-spec/shared/idempotency';
+ *
+ * const downstreamKey = deriveIdempotencyKey(
+ *   IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR,
+ *   'agent.start',
+ *   runId,
+ *   agentId,
+ * );
+ * ```
+ *
+ * @see ./idempotency-shape.ts — browser-safe primitives
+ */
+export { IDEMPOTENCY_KEY_MAX_LENGTH, IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR, type IdempotencyKey, IdempotencyKeyScalar, validateIdempotencyKey, } from './idempotency-shape.js';
+/**
+ * Derive a deterministic idempotency key (UUID v5) from a namespace and an
+ * ordered list of seed parts. Each part is coerced to its string form and
+ * joined with a `` (ASCII unit-separator) delimiter — chosen because
+ * it cannot legally appear in caller strings, so collision is impossible
+ * for normal inputs.
+ *
+ * Per SEAMS.md S-02 / S-03 / S-06 / S-07: outbox-derived downstream calls
+ * MUST use this helper to derive their idempotency key from
+ * `(outerKey, calleeDomain, calleeOp, ...subjectIds)` so replays converge.
+ */
+export declare function deriveIdempotencyKey(namespace: string, ...parts: ReadonlyArray<string | number>): string;
+/**
+ * RFC 4122 §4.3 UUID v5:
+ *   1. Concat namespace bytes (16) || name UTF-8 bytes.
+ *   2. SHA-1 hash.
+ *   3. Take first 16 bytes.
+ *   4. Set version nibble to 5: `bytes[6] = (bytes[6] & 0x0f) | 0x50`.
+ *   5. Set variant nibble to RFC 4122: `bytes[8] = (bytes[8] & 0x3f) | 0x80`.
+ *
+ * Exported for the namespace-derivation regression test in
+ * `./shared.test.ts`; external callers use `deriveIdempotencyKey()`.
+ */
+export declare function uuidV5(namespace: string, name: string): string;

package/dist/shared/idempotency.js

@@ -0,0 +1 @@
+import{bytesToHex as s,sha1 as c}from"@lssm/lib.crypto-utils";export{IDEMPOTENCY_KEY_MAX_LENGTH,IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR,IdempotencyKeyScalar,validateIdempotencyKey}from"./idempotency-shape.js";export function deriveIdempotencyKey(n,...e){if(!y(n))throw Error(`deriveIdempotencyKey: namespace must be a canonical UUID; got "${n}".`);if(e.length===0)throw Error("deriveIdempotencyKey: at least one seed part is required.");const r=e.map((t)=>String(t)).join("");return uuidV5(n,r)}const a=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;function y(n){return a.test(n)}function l(n){const e=n.replace(/-/g,""),r=new Uint8Array(e.length/2);for(let t=0;t<r.length;t+=1)r[t]=Number.parseInt(e.slice(t*2,t*2+2),16);return r}function d(n){const e=s(n);return`${e.slice(0,8)}-${e.slice(8,12)}-${e.slice(12,16)}-${e.slice(16,20)}-${e.slice(20,32)}`}export function uuidV5(n,e){const r=l(n),t=new TextEncoder().encode(e),i=new Uint8Array(r.length+t.length);i.set(r);i.set(t,r.length);const o=c(i).slice(0,16);o[6]=(o[6]??0)&15|80;o[8]=(o[8]??0)&63|128;return d(o)}

package/dist/shared/index.d.js

@@ -0,0 +1 @@
+export*from"./attach-context.js";export*from"./audit.js";export*from"./idempotency-shape.js";export*from"./window.js";

package/dist/shared/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared primitives referenced by ≥3 seams in SEAMS.md.
+ *
+ * Phase 0.3.G shape promotions (Q-08). **This barrel is browser-safe.** It
+ * re-exports only modules that do not import `node:crypto` or any
+ * Node-only runtime. Enforced by the root browser-surface test
+ * (`../index.browser-surface.test.ts`).
+ *
+ * Phase 0.4 contract authors import from this barrel:
+ *
+ *   import {
+ *     WindowDescriptor,
+ *     WindowDescriptorSchema,
+ *     validateWindowDescriptor,
+ *     AuditEventId,
+ *     AuditRecordSummary,
+ *     AuditRecordSummarySchema,
+ *     IdempotencyKey,
+ *     IdempotencyKeyScalar,
+ *     IDEMPOTENCY_NAMESPACE_AGENT_WORKFLOW_PILLAR,
+ *     validateIdempotencyKey,
+ *     AttachContext,
+ *     AttachContextSchema,
+ *     validateAttachContext,
+ *   } from '@lssm/lib.contracts-spec/shared';
+ *
+ * The Node-only `deriveIdempotencyKey()` UUID v5 helper is reached via an
+ * explicit subpath (mirrors `rich-reference/denial-token.ts`):
+ *
+ *   import { deriveIdempotencyKey } from '@lssm/lib.contracts-spec/shared/idempotency';
+ *
+ * Used by the outbox adapter (task #34) and any Phase 2 handler that
+ * derives downstream keys from outer caller context (S-02, S-03, S-06,
+ * S-07).
+ */
+export * from './attach-context.js';
+export * from './audit.js';
+export * from './idempotency-shape.js';
+export * from './window.js';

package/dist/shared/index.js

@@ -0,0 +1 @@
+export*from"./attach-context.js";export*from"./audit.js";export*from"./idempotency-shape.js";export*from"./window.js";

package/dist/shared/window.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `WindowDescriptor` — canonical time-window shape shared across domains.
+ *
+ * Phase 0.3.G shape promotion (SEAMS.md §4, Q-08). Used by:
+ *  - `fleet.metrics.summary` / `fleet.health.snapshot` / `fleet.roi.snapshot`
+ *    (S-10 aggregation seam — fleet ops accept this shape and forward it to
+ *    source domains unchanged per §1.2 caller-context propagation).
+ *  - `governance.policy.simulate` (`windowDays` is a `WindowDescriptor`
+ *    short-form).
+ *  - `audit.event.list` (`from` / `to` flow through this shape).
+ *  - Any future aggregating op that needs a calibrated time range.
+ *
+ * Design contract:
+ *  - `from` and `to` are ISO-8601 UTC timestamps. Local times are forbidden;
+ *    the caller is responsible for converting before the contract boundary.
+ *  - `to` MUST be strictly greater than `from`. Equal timestamps are a
+ *    `VALIDATION` error (caller almost certainly means "now" — must be
+ *    explicit).
+ *  - `granularity` is advisory: source domains MAY downsample further if a
+ *    coarser bucket fits their materialization. Source domains MUST NOT
+ *    upsample (re-bucket finer than `granularity`) — that's a §3.10 (S-10)
+ *    "fleet's role is pass-through" invariant violation.
+ *  - The shape is shallow & immutable on purpose — agents and replay tools
+ *    can hash a `WindowDescriptor` as part of their idempotency key.
+ *
+ * Re-validation on output is unnecessary: this is a request-side input
+ * primitive; responses use the same shape echoed back when relevant.
+ *
+ * @see ./idempotency.ts — `deriveIdempotencyKey(NS, window.from, window.to, ...)`
+ */
+import { SchemaModel } from '@lssm/lib.schema';
+/** Time-bucket granularity supported by aggregating ops. */
+export type WindowGranularity = 'minute' | 'hour' | 'day' | 'week' | 'month';
+export declare const WINDOW_GRANULARITIES: readonly WindowGranularity[];
+/**
+ * Calibrated time window. Inclusive on `from`, exclusive on `to` (half-open
+ * interval) to match standard streaming-query semantics.
+ */
+export interface WindowDescriptor {
+    /** ISO-8601 UTC timestamp (inclusive). */
+    from: string;
+    /** ISO-8601 UTC timestamp (exclusive). MUST be strictly greater than `from`. */
+    to: string;
+    /** Bucket granularity for materialization. Advisory — see file header. */
+    granularity: WindowGranularity;
+}
+/**
+ * SchemaModel for `WindowDescriptor`. Phase 0.4 authors reference this
+ * directly inside `io.input` SchemaModel composition; SchemaModel today does
+ * not nest, so Phase 0.4 authors copy these three fields by name into their
+ * input schema and reference `WINDOW_GRANULARITIES` for the enum constraint.
+ *
+ * Exported as a SchemaModel for completeness; the TypeScript type
+ * `WindowDescriptor` is the canonical handler-side reference.
+ */
+export declare const WindowDescriptorSchema: SchemaModel<{
+    from: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    to: {
+        type: import("@lssm/lib.schema").FieldType<Date, string>;
+        isOptional: false;
+    };
+    granularity: {
+        type: import("@lssm/lib.schema").FieldType<string, string>;
+        isOptional: false;
+    };
+}>;
+/**
+ * Runtime predicate for `WindowDescriptor.granularity`. Use this in
+ * handlers (NOT in contract validation — the SchemaModel above handles
+ * shape; this predicate refines the enum).
+ */
+export declare function isWindowGranularity(value: unknown): value is WindowGranularity;
+/**
+ * Validate `from < to` and granularity is in the supported set. Returns an
+ * error message on failure, `null` on success. Handlers SHOULD call this
+ * before threading the window into a downstream source domain.
+ */
+export declare function validateWindowDescriptor(window: WindowDescriptor): string | null;

package/dist/shared/window.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as i}from"@lssm/lib.schema";export const WINDOW_GRANULARITIES=["minute","hour","day","week","month"];export const WindowDescriptorSchema=new i({name:"WindowDescriptor",fields:{from:{type:t.DateTime(),isOptional:!1},to:{type:t.DateTime(),isOptional:!1},granularity:{type:t.NonEmptyString(),isOptional:!1}}});export function isWindowGranularity(r){return typeof r==="string"&&WINDOW_GRANULARITIES.includes(r)}export function validateWindowDescriptor(r){if(!isWindowGranularity(r.granularity))return`WindowDescriptor.granularity must be one of ${WINDOW_GRANULARITIES.join(", ")}; got "${r.granularity}".`;const o=Date.parse(r.from),e=Date.parse(r.to);if(Number.isNaN(o))return`WindowDescriptor.from is not a valid ISO-8601 timestamp: "${r.from}".`;if(Number.isNaN(e))return`WindowDescriptor.to is not a valid ISO-8601 timestamp: "${r.to}".`;if(e<=o)return`WindowDescriptor.to (${r.to}) must be strictly greater than from (${r.from}).`;return null}

package/dist/shared-entities/index.d.ts

@@ -0,0 +1,8 @@
+export { PersonEntity, shared_entities_person_DocBlocks } from './person.js';
+export { ProjectEntity, shared_entities_project_DocBlocks } from './project.js';
+export { ResourceEntity, shared_entities_resource_DocBlocks } from './resource.js';
+export type { SharedTask, SharedTaskStatus } from './task.js';
+export { SharedTaskStatusEnum, shared_entities_task_DocBlocks, TaskEntity, } from './task.js';
+export type { TaskValidationResult } from './task-validators.js';
+export { shared_entities_task_validators_DocBlocks, validateAgentTask, validateAgentTasks, validateWorkflowTask, validateWorkflowTasks, } from './task-validators.js';
+export { shared_entities_team_DocBlocks, TeamEntity } from './team.js';

package/dist/shared-entities/index.js

@@ -0,0 +1 @@
+export{PersonEntity,shared_entities_person_DocBlocks}from"./person.js";export{ProjectEntity,shared_entities_project_DocBlocks}from"./project.js";export{ResourceEntity,shared_entities_resource_DocBlocks}from"./resource.js";export{SharedTaskStatusEnum,shared_entities_task_DocBlocks,TaskEntity}from"./task.js";export{shared_entities_task_validators_DocBlocks,validateAgentTask,validateAgentTasks,validateWorkflowTask,validateWorkflowTasks}from"./task-validators.js";export{shared_entities_team_DocBlocks,TeamEntity}from"./team.js";

package/dist/shared-entities/person.d.ts

@@ -0,0 +1,50 @@
+import type { DocBlock } from '../docs/types.js';
+/**
+ * Canonical cross-domain Person entity (Layer 1: slug + edges, M2).
+ * @example
+ * ```typescript
+ * const registry = new EntityRegistry([PersonEntity]);
+ * registry.get('person'); // ContractEntitySpec
+ * ```
+ */
+export declare const PersonEntity: {
+    readonly meta: {
+        readonly key: "person";
+        readonly version: "1.0.0";
+        readonly description: "A human actor in the system — user, team member, or contact.";
+        readonly title: "Person";
+        readonly domain: "shared";
+        readonly stability: 'stable';
+        readonly owners: ["platform.core"];
+        readonly tags: ["person", "shared", "cross-domain"];
+    };
+    readonly edges: [{
+        readonly id: "person-to-team";
+        readonly from: "person";
+        readonly to: "team";
+        readonly relation: "member-of";
+        readonly cardinality: 'many-to-many';
+        readonly directed: true;
+        readonly label: "Member of";
+        readonly inverse: "team-to-person";
+    }, {
+        readonly id: "person-to-project";
+        readonly from: "person";
+        readonly to: "project";
+        readonly relation: "contributes-to";
+        readonly cardinality: 'many-to-many';
+        readonly directed: true;
+        readonly label: "Contributes to";
+        readonly inverse: "project-to-person";
+    }, {
+        readonly id: "person-to-task";
+        readonly from: "person";
+        readonly to: "task";
+        readonly relation: "assigned-to";
+        readonly cardinality: 'one-to-many';
+        readonly directed: true;
+        readonly label: "Assigned tasks";
+        readonly inverse: "task-to-person";
+    }];
+};
+export declare const shared_entities_person_DocBlocks: DocBlock[];

package/dist/shared-entities/person.js

@@ -0,0 +1,12 @@
+import{defineContractEntity as t}from"../entities/defineContractEntity.js";export const PersonEntity=t({meta:{key:"person",version:"1.0.0",description:"A human actor in the system \u2014 user, team member, or contact.",title:"Person",domain:"shared",stability:"stable",owners:["platform.core"],tags:["person","shared","cross-domain"]},edges:[{id:"person-to-team",from:"person",to:"team",relation:"member-of",cardinality:"many-to-many",directed:!0,label:"Member of",inverse:"team-to-person"},{id:"person-to-project",from:"person",to:"project",relation:"contributes-to",cardinality:"many-to-many",directed:!0,label:"Contributes to",inverse:"project-to-person"},{id:"person-to-task",from:"person",to:"task",relation:"assigned-to",cardinality:"one-to-many",directed:!0,label:"Assigned tasks",inverse:"task-to-person"}]});export const shared_entities_person_DocBlocks=[{id:"docs.tech.contracts.shared-entities.person",title:"PersonEntity \u2014 Cross-Domain Person Contract Entity",summary:"`PersonEntity` is the canonical cross-domain entity for a human actor. Layer 1: `person` slug with edges to team, project, and task.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/person",tags:["tech","contracts","shared-entities","person"],body:`# PersonEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'person'\`.
+
+## Edges
+
+| ID | From | To | Relation | Cardinality |
+|----|----|----|----|----|
+| \`person-to-team\` | person | team | member-of | many-to-many |
+| \`person-to-project\` | person | project | contributes-to | many-to-many |
+| \`person-to-task\` | person | task | assigned-to | one-to-many |
+`}];

package/dist/shared-entities/project.d.ts

@@ -0,0 +1,53 @@
+import type { DocBlock } from '../docs/types.js';
+/**
+ * Canonical cross-domain Project entity (Layer 1: slug + edges, M2).
+ */
+export declare const ProjectEntity: {
+    readonly meta: {
+        readonly key: "project";
+        readonly version: "1.0.0";
+        readonly description: "A bounded initiative owned by a team, involving persons and tasks.";
+        readonly title: "Project";
+        readonly domain: "shared";
+        readonly stability: 'stable';
+        readonly owners: ["platform.core"];
+        readonly tags: ["project", "shared", "cross-domain"];
+    };
+    readonly edges: [{
+        readonly id: "project-to-team";
+        readonly from: "project";
+        readonly to: "team";
+        readonly relation: "owned-by";
+        readonly cardinality: 'many-to-one';
+        readonly directed: true;
+        readonly label: "Owned by";
+        readonly inverse: "team-to-project";
+    }, {
+        readonly id: "project-to-person";
+        readonly from: "project";
+        readonly to: "person";
+        readonly relation: "contributed-by";
+        readonly cardinality: 'many-to-many';
+        readonly directed: true;
+        readonly label: "Contributors";
+        readonly inverse: "person-to-project";
+    }, {
+        readonly id: "project-to-task";
+        readonly from: "project";
+        readonly to: "task";
+        readonly relation: "has-task";
+        readonly cardinality: 'one-to-many';
+        readonly directed: true;
+        readonly label: "Tasks";
+        readonly inverse: "task-to-project";
+    }, {
+        readonly id: "project-to-resource";
+        readonly from: "project";
+        readonly to: "resource";
+        readonly relation: "uses";
+        readonly cardinality: 'many-to-many';
+        readonly directed: true;
+        readonly label: "Resources";
+    }];
+};
+export declare const shared_entities_project_DocBlocks: DocBlock[];

package/dist/shared-entities/project.js

@@ -0,0 +1,4 @@
+import{defineContractEntity as t}from"../entities/defineContractEntity.js";export const ProjectEntity=t({meta:{key:"project",version:"1.0.0",description:"A bounded initiative owned by a team, involving persons and tasks.",title:"Project",domain:"shared",stability:"stable",owners:["platform.core"],tags:["project","shared","cross-domain"]},edges:[{id:"project-to-team",from:"project",to:"team",relation:"owned-by",cardinality:"many-to-one",directed:!0,label:"Owned by",inverse:"team-to-project"},{id:"project-to-person",from:"project",to:"person",relation:"contributed-by",cardinality:"many-to-many",directed:!0,label:"Contributors",inverse:"person-to-project"},{id:"project-to-task",from:"project",to:"task",relation:"has-task",cardinality:"one-to-many",directed:!0,label:"Tasks",inverse:"task-to-project"},{id:"project-to-resource",from:"project",to:"resource",relation:"uses",cardinality:"many-to-many",directed:!0,label:"Resources"}]});export const shared_entities_project_DocBlocks=[{id:"docs.tech.contracts.shared-entities.project",title:"ProjectEntity \u2014 Cross-Domain Project Contract Entity",summary:"`ProjectEntity` is the canonical cross-domain entity for a bounded initiative. Layer 1: `project` slug with edges to team, person, task, resource.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/project",tags:["tech","contracts","shared-entities","project"],body:`# ProjectEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'project'\`.
+`}];

package/dist/shared-entities/resource.d.ts

@@ -0,0 +1,36 @@
+import type { DocBlock } from '../docs/types.js';
+/**
+ * Canonical cross-domain Resource entity (Layer 1: slug + edges, M2).
+ */
+export declare const ResourceEntity: {
+    readonly meta: {
+        readonly key: "resource";
+        readonly version: "1.0.0";
+        readonly description: "A managed asset (credential, compute, budget, external service) used by teams and projects.";
+        readonly title: "Resource";
+        readonly domain: "shared";
+        readonly stability: 'stable';
+        readonly owners: ["platform.core"];
+        readonly tags: ["resource", "shared", "cross-domain"];
+    };
+    readonly edges: [{
+        readonly id: "resource-to-team";
+        readonly from: "resource";
+        readonly to: "team";
+        readonly relation: "managed-by";
+        readonly cardinality: 'many-to-one';
+        readonly directed: true;
+        readonly label: "Managed by";
+        readonly inverse: "team-to-resource";
+    }, {
+        readonly id: "resource-to-project";
+        readonly from: "resource";
+        readonly to: "project";
+        readonly relation: "used-by";
+        readonly cardinality: 'many-to-many';
+        readonly directed: true;
+        readonly label: "Used by projects";
+        readonly inverse: "project-to-resource";
+    }];
+};
+export declare const shared_entities_resource_DocBlocks: DocBlock[];

package/dist/shared-entities/resource.js

@@ -0,0 +1,4 @@
+import{defineContractEntity as e}from"../entities/defineContractEntity.js";export const ResourceEntity=e({meta:{key:"resource",version:"1.0.0",description:"A managed asset (credential, compute, budget, external service) used by teams and projects.",title:"Resource",domain:"shared",stability:"stable",owners:["platform.core"],tags:["resource","shared","cross-domain"]},edges:[{id:"resource-to-team",from:"resource",to:"team",relation:"managed-by",cardinality:"many-to-one",directed:!0,label:"Managed by",inverse:"team-to-resource"},{id:"resource-to-project",from:"resource",to:"project",relation:"used-by",cardinality:"many-to-many",directed:!0,label:"Used by projects",inverse:"project-to-resource"}]});export const shared_entities_resource_DocBlocks=[{id:"docs.tech.contracts.shared-entities.resource",title:"ResourceEntity \u2014 Cross-Domain Resource Contract Entity",summary:"`ResourceEntity` is the canonical cross-domain entity for a managed asset. Layer 1: `resource` slug with edges to team and project.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/resource",tags:["tech","contracts","shared-entities","resource"],body:`# ResourceEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'resource'\`.
+`}];