@kindgi/types 0.0.0-bootstrap.0 → 0.1.0

package/src/ids.test-d.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { assertType, describe, expectTypeOf, test } from 'vitest';
+import type { AgentId, Brand, TenantId, ToolId, UserId } from './ids.js';
+
+describe('branded IDs', () => {
+  test('a branded id is assignable from a cast, not from a bare string', () => {
+    const raw = 'abc';
+    // A cast is the sanctioned way to construct a branded id.
+    const tenant: TenantId = raw as TenantId;
+    expectTypeOf(tenant).toEqualTypeOf<TenantId>();
+    // A bare string is NOT assignable to a branded id (compile error).
+    // @ts-expect-error — bare string cannot be assigned to a branded id.
+    const _bad: TenantId = raw;
+  });
+
+  test('two different branded ids are not interchangeable', () => {
+    const tenant = 'abc' as TenantId;
+    // TenantId is not assignable to UserId, and vice versa.
+    // @ts-expect-error — TenantId is not a UserId.
+    const _asUser: UserId = tenant;
+    // @ts-expect-error — a UserId literal isn't automatically a TenantId either.
+    const _asTenant: TenantId = 'u1' as UserId;
+  });
+
+  test('branded ids still behave structurally as strings', () => {
+    const tool = 'acme.verify-citation' as ToolId;
+    // String operations preserve the underlying primitive.
+    expectTypeOf(tool.length).toEqualTypeOf<number>();
+    expectTypeOf(tool.toString()).toEqualTypeOf<string>();
+    // But the operation result is NOT branded (any string producer drops the brand).
+    expectTypeOf(`${tool}`).toEqualTypeOf<string>();
+  });
+
+  test('Brand utility composes cleanly for pack-scoped ids', () => {
+    type MatterId = Brand<string, 'MatterId'>;
+    const matter = 'm-42' as MatterId;
+    expectTypeOf(matter).toEqualTypeOf<MatterId>();
+    // Pack-scoped ids don't collide with framework ids.
+    // @ts-expect-error — MatterId is not an AgentId.
+    const _agent: AgentId = matter;
+  });
+
+  test('assertType negative: passing wrong id shape must fail at call site', () => {
+    function useTenant(t: TenantId): void {
+      assertType<TenantId>(t);
+    }
+    const tenant = 'abc' as TenantId;
+    useTenant(tenant);
+    // @ts-expect-error — a UserId cannot be passed where TenantId is expected.
+    useTenant('u1' as UserId);
+  });
+});

package/src/ids.ts

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Branded ID types for every entity kind in Kindgi.
+ *
+ * Every ID is a nominal string type — structurally a string, but statically distinct.
+ * A `TenantId` cannot be passed where a `UserId` is expected, catching a whole class
+ * of bugs at compile time.
+ *
+ * These are pure compile-time constructs; there is no runtime cost. Construction
+ * is by cast (`as`). The one exception is `EnvName`, which has the validated
+ * factory `makeEnvName` (the only runtime export of this package); validation of
+ * wire payloads lives in `@kindgi/schema`.
+ *
+ * Naming convention:
+ *   - `<Entity>Id`     — a single identifier for that entity kind.
+ *   - Most entity kinds in the `@kindgi/specs/*.schema.json` files have an ID
+ *     here (eval suites, for one, use plain strings); some IDs (e.g.
+ *     `ConversationId`, `TriggerId`) name entities that have no schema.
+ *
+ * If you add a new entity kind to Kindgi, add its ID here. Consumers rely on
+ * this being the canonical registry of branded IDs.
+ */
+
+/**
+ * Generic brand utility. Prefer using the pre-defined branded types below;
+ * this is exported for downstream packs that need to declare pack-scoped IDs
+ * (e.g. `Brand<string, 'MatterId'>` in a pack that tracks legal matters).
+ */
+export type Brand<T, B extends string> = T & { readonly __brand: B };
+
+/**
+ * `T` with every branded string in it (`FlowId`, `NodeId`, `EdgeId`, …)
+ * loosened to plain `string`, all the way down: through arrays, objects
+ * and unions. For authoring inputs, so an author writes `'acme.review'`
+ * rather than `'acme.review' as FlowId`. A branded value still fits, since
+ * it is a string. The validated result is branded again.
+ */
+export type Unbranded<T> = T extends string & { readonly __brand: string }
+  ? string
+  : T extends readonly (infer E)[]
+    ? readonly Unbranded<E>[]
+    : T extends object
+      ? { readonly [K in keyof T]: Unbranded<T[K]> }
+      : T;
+
+/** Tenant — the sovereignty boundary. Cross-tenant access is denied by policy. */
+export type TenantId = Brand<string, 'TenantId'>;
+
+/** User within a tenant. */
+export type UserId = Brand<string, 'UserId'>;
+
+/** Organization scope within a tenant — optional structural subdivision (a firm's litigation department, a hospital's cardiology). Small tenants ignore this; large tenants use it. */
+export type OrgId = Brand<string, 'OrgId'>;
+
+/** Team scope — a people-group. A named collection of users who work together; users can belong to many teams. Same team works on many projects; same project can have many teams collaborating. Distinct from Org (structural) — Team is about working groups. */
+export type TeamId = Brand<string, 'TeamId'>;
+
+/** Project scope — vertical-agnostic ('matter' in legal, 'case' in HR, 'engagement' in accounting, 'episode' in healthcare). This is the primary content-scope: facts, artifacts, runs, blobs belong to a project. */
+export type ProjectId = Brand<string, 'ProjectId'>;
+
+/** Conversation thread within a session. */
+export type ThreadId = Brand<string, 'ThreadId'>;
+
+/**
+ * Agent conversation. A conversation is a first-class primitive (see the
+ * `agent_conversations` migration in `@kindgi/agents`): it groups many
+ * agent invocations into one durable thread the user can reopen, hand
+ * off, or reference in a later run. Distinct from `ThreadId` (which is a
+ * lower-level session-thread identifier used by the session store).
+ */
+export type ConversationId = Brand<string, 'ConversationId'>;
+
+/** User session. */
+export type SessionId = Brand<string, 'SessionId'>;
+
+/** A run — one execution of a flow. */
+export type RunId = Brand<string, 'RunId'>;
+
+/**
+ * Task flow definition id. Convention: `<pack-id>.<flow-name>`
+ * (kebab-case, dot-namespaced) — e.g. `acme.brief-review-flow`,
+ * `demo.echo-flow`. The framework's built-in agent-turn flow is
+ * `agent.turn` (`AGENT_TURN_FLOW_ID` in `@kindgi/agents`).
+ */
+export type FlowId = Brand<string, 'FlowId'>;
+
+/** A node within a flow. Convention: kebab-case, unique within the flow — e.g. `dispatch-tool`, `wait-for-approval`. */
+export type NodeId = Brand<string, 'NodeId'>;
+
+/** An edge within a flow. Declared by the flow author (`FlowEdge.id` in `@kindgi/flow`); must be unique across the flow, including its loop bodies. */
+export type EdgeId = Brand<string, 'EdgeId'>;
+
+/**
+ * Agent definition id. Convention: `<pack-id>.<agent-name>`
+ * (kebab-case, dot-namespaced) — e.g. `acme.brief-writer`,
+ * `demo.echo-agent`. The `<pack-id>` prefix scopes the agent to
+ * its pack; `<agent-name>` describes the agent's role. Enforced by
+ * `defineAgent` at author time.
+ */
+export type AgentId = Brand<string, 'AgentId'>;
+
+/**
+ * Tool definition id. Convention: `<pack-id>.<tool-name>`
+ * (kebab-case, dot-namespaced) — e.g. `acme.verify-citation`,
+ * `demo.echo`. The `<pack-id>` prefix scopes the tool to its pack;
+ * `<tool-name>` names the operation. Enforced by `defineTool` at
+ * author time.
+ */
+export type ToolId = Brand<string, 'ToolId'>;
+
+/**
+ * Guardrail declaration id. Convention: `<pack-id>.<guardrail-name>`
+ * (kebab-case, dot-namespaced) — e.g. `acme.no-fabricated-quotes`,
+ * `demo.response-not-empty`. `<guardrail-name>` describes the
+ * property being asserted (usually a positive rule the agent turn
+ * must satisfy). Enforced by `defineGuardrail` at author time.
+ */
+export type GuardrailId = Brand<string, 'GuardrailId'>;
+
+/** A tenant policy document. */
+export type PolicyId = Brand<string, 'PolicyId'>;
+
+/** A pack manifest (installable vertical application). */
+export type PackId = Brand<string, 'PackId'>;
+
+/** An event (runtime-emitted or user-emitted). */
+export type EventId = Brand<string, 'EventId'>;
+
+/** A memory Fact — typed, versioned, retrievable. */
+export type FactId = Brand<string, 'FactId'>;
+
+/** A memory LogEntry — one line in the append-only event stream. */
+export type LogEntryId = Brand<string, 'LogEntryId'>;
+
+/** A generated artifact (draft, memo, report). */
+export type ArtifactId = Brand<string, 'ArtifactId'>;
+
+/** A provenance DAG record. */
+export type ProvenanceId = Brand<string, 'ProvenanceId'>;
+
+/** A subscription registration for the events system. */
+export type SubscriptionId = Brand<string, 'SubscriptionId'>;
+
+/** An approval request in the HITL queue. */
+export type ApprovalId = Brand<string, 'ApprovalId'>;
+
+/** A reviewer registered with HITL — carries a role class (standard/senior/admin). */
+export type ReviewerId = Brand<string, 'ReviewerId'>;
+
+/** A supervisor definition — the actor that observes runs and proposes fixes. */
+export type SupervisorId = Brand<string, 'SupervisorId'>;
+
+/** A recorded supervisor observation of a single agent run. */
+export type ObservationId = Brand<string, 'ObservationId'>;
+
+/** A supervisor's proposed fix to an agent artifact (prompt / retrieval / tool-config). */
+export type FixProposalId = Brand<string, 'FixProposalId'>;
+
+/** A signed audit bundle exported from HITL. Wraps approvals + evidence + provenance refs. */
+export type AuditBundleId = Brand<string, 'AuditBundleId'>;
+
+/** A compliance evidence bundle. */
+export type ComplianceEvidenceId = Brand<string, 'ComplianceEvidenceId'>;
+
+/** A wait token issued for pausing a run (HITL, external callback). */
+export type WaitTokenId = Brand<string, 'WaitTokenId'>;
+
+/** A training dataset registered in memory. */
+export type DatasetId = Brand<string, 'DatasetId'>;
+
+/** A recurring schedule that triggers agent / flow runs on a cadence. */
+export type ScheduleId = Brand<string, 'ScheduleId'>;
+
+/** A registered capability provider (model provider, embedding provider, etc.). */
+export type ProviderId = Brand<string, 'ProviderId'>;
+
+/** An API token issued to a caller for authenticating platform requests. */
+export type ApiTokenId = Brand<string, 'ApiTokenId'>;
+
+/** The routable public identifier of an inbound webhook trigger: the id in its receiver URL (see `TriggerId`). */
+export type WebhookId = Brand<string, 'WebhookId'>;
+
+/** An outbound webhook endpoint: a URL the platform sends signed events to. */
+export type WebhookEndpointId = Brand<string, 'WebhookEndpointId'>;
+
+/** One outbound webhook event. Sent as the `webhook-id` header and the same on every retry, so receivers deduplicate on it. */
+export type WebhookEventId = Brand<string, 'WebhookEventId'>;
+
+/** One event's delivery to one outbound endpoint, across all its attempts. */
+export type WebhookDeliveryId = Brand<string, 'WebhookDeliveryId'>;
+
+/** An installed pack instance for a tenant. Reserved: no package in this repository issues one. */
+export type InstallationId = Brand<string, 'InstallationId'>;
+
+/** A signing key — identifies a key pair in a caller-provided key store (see `SigningKeyBinding` in `@kindgi/crypto`). Keys themselves are opaque `Uint8Array` values; this ID is how consumers reference them at runtime without owning the store. */
+export type SigningKeyId = Brand<string, 'SigningKeyId'>;
+
+/** A registered trigger — its storage primary key. Distinct from `WebhookId` (routable public identifier used on the receiver URL); a webhook trigger has both a `TriggerId` (private, primary key) and a `WebhookId` (public, routable). */
+export type TriggerId = Brand<string, 'TriggerId'>;
+
+/**
+ * A per-environment slug carried as a required dimension by `EnvBinding`
+ * and `SecretBinding`.
+ *
+ * Grammar: `[a-z][a-z0-9-]{0,62}` — RFC-1035-like label (lowercase alnum
+ * + hyphen, 1–63 chars, starts with a letter). Cross-provider portable
+ * (Vault path chars, GCP secret names, AWS ARN paths, k8s namespaces).
+ * Use `makeEnvName` for validated construction; unchecked casts are
+ * a policy violation for any code path that receives external input.
+ */
+export type EnvName = Brand<string, 'EnvName'>;
+
+const ENV_NAME_GRAMMAR = /^[a-z][a-z0-9-]{0,62}$/;
+
+/**
+ * Validated `EnvName` factory. Returns `null` on any grammar violation
+ * (uppercase, underscore, dot, slash, non-ASCII, empty, >63 chars).
+ */
+export function makeEnvName(raw: string): EnvName | null {
+  if (typeof raw !== 'string') return null;
+  if (!ENV_NAME_GRAMMAR.test(raw)) return null;
+  return raw as EnvName;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export type * from './filter.js';
+export type * from './hash.js';
+export type * from './ids.js';
+export type * from './refs.js';
+export type * from './result.js';
+export type * from './temporal.js';
+export type * from './version.js';
+
+// Runtime factories on branded IDs (validated construction). Kept as a
+// separate value re-export so the `export type *` barrels above stay
+// pure-type — value exports live only where explicitly listed.
+export { makeEnvName } from './ids.js';

package/src/refs.test-d.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { describe, expectTypeOf, test } from 'vitest';
+import type { ContentHash, KeyId } from './hash.js';
+import type { TenantId } from './ids.js';
+import type { BlobRef, DatasetRef } from './refs.js';
+import type { Timestamp } from './temporal.js';
+
+describe('BlobRef', () => {
+  test('all required fields present and typed correctly', () => {
+    const ref: BlobRef = {
+      provider: 'minio',
+      bucket: 'kindgi-blobs',
+      key: 'tenants/abc/uploads/doc-42',
+      size: 1024,
+      sha256: 'sha256:abc' as ContentHash,
+      contentType: 'application/pdf',
+      tenantId: 'abc' as TenantId,
+      createdAt: '2026-09-16T14:00:00Z' as Timestamp,
+    };
+    expectTypeOf(ref.provider).toEqualTypeOf<string>();
+    expectTypeOf(ref.sha256).toEqualTypeOf<ContentHash>();
+    expectTypeOf(ref.tenantId).toEqualTypeOf<TenantId>();
+  });
+
+  test('retentionUntil is optional', () => {
+    const withoutRetention: BlobRef = {
+      provider: 'minio',
+      bucket: 'b',
+      key: 'k',
+      size: 0,
+      sha256: 'sha256:0' as ContentHash,
+      contentType: 'application/octet-stream',
+      tenantId: 'abc' as TenantId,
+      createdAt: '2026-09-16T14:00:00Z' as Timestamp,
+    };
+    expectTypeOf(withoutRetention.retentionUntil).toEqualTypeOf<Timestamp | undefined>();
+  });
+
+  test('missing required fields fail at compile time', () => {
+    // @ts-expect-error — 'bucket' is required.
+    const _bad: BlobRef = {
+      provider: 'minio',
+      key: 'k',
+      size: 0,
+      sha256: 'sha256:0' as ContentHash,
+      contentType: 'application/octet-stream',
+      tenantId: 'abc' as TenantId,
+      createdAt: '2026-09-16T14:00:00Z' as Timestamp,
+    };
+  });
+
+  test('fields are readonly', () => {
+    const ref: BlobRef = {
+      provider: 'minio',
+      bucket: 'b',
+      key: 'k',
+      size: 0,
+      sha256: 'sha256:0' as ContentHash,
+      contentType: 'application/octet-stream',
+      tenantId: 'abc' as TenantId,
+      createdAt: '2026-09-16T14:00:00Z' as Timestamp,
+    };
+    // @ts-expect-error — bucket is readonly.
+    ref.bucket = 'other';
+  });
+});
+
+describe('DatasetRef', () => {
+  test('has the expected shape', () => {
+    const ref: DatasetRef = {
+      datasetId: 'acme.contract-eval',
+      tenantId: 'abc' as TenantId,
+      version: '1.0.0',
+      factType: 'acme.contract',
+      count: 128,
+      createdAt: '2026-09-16T14:00:00Z' as Timestamp,
+    };
+    expectTypeOf(ref.count).toEqualTypeOf<number>();
+    expectTypeOf(ref.factType).toEqualTypeOf<string>();
+  });
+});
+
+describe('KeyId is opaque', () => {
+  test('constructed via cast', () => {
+    const k = 'ed25519-local:tenant-abc-v1' as KeyId;
+    expectTypeOf(k).toEqualTypeOf<KeyId>();
+    // KeyId is not string-assignable without cast.
+    // @ts-expect-error — bare string is not a KeyId.
+    const _bad: KeyId = 'foo';
+  });
+});

package/src/refs.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ContentHash } from './hash.js';
+import type { TenantId } from './ids.js';
+import type { Timestamp } from './temporal.js';
+
+/**
+ * Reference to a blob in object storage.
+ *
+ * BlobRef is a handle to bytes held by an object-storage provider (e.g.
+ * MinIO, S3, R2, GCS).
+ *
+ * The required fields are populated by the storage layer that wrote the
+ * bytes. Consumers must NEVER construct a BlobRef by hand; a real one always
+ * comes from a provider that has already written the bytes.
+ */
+export interface BlobRef {
+  /** Which provider holds this blob (e.g. 'minio', 's3', 'r2', 'gcs'). */
+  readonly provider: string;
+  /** Bucket name within the provider. */
+  readonly bucket: string;
+  /** Object key within the bucket. Never contains a leading slash. */
+  readonly key: string;
+  /** Size in bytes. */
+  readonly size: number;
+  /** Content hash of the blob bytes — enables dedup and tamper detection. */
+  readonly sha256: ContentHash;
+  /** MIME type. */
+  readonly contentType: string;
+  /** Owning tenant. Cross-tenant access is denied by policy. */
+  readonly tenantId: TenantId;
+  /** When the blob was written. */
+  readonly createdAt: Timestamp;
+  /**
+   * Optional retention lock — after this timestamp, provider MAY delete;
+   * before, provider MUST refuse deletion. Enables legal-hold semantics.
+   */
+  readonly retentionUntil?: Timestamp;
+}
+
+/**
+ * Reference to a versioned dataset: a collection of memory Facts (see
+ * `@kindgi/memory`) of one declared type — e.g. eval corpora, held-out sets,
+ * or examples a pack ships with.
+ *
+ * The DatasetRef captures which collection and which version.
+ */
+export interface DatasetRef {
+  /** Dataset identifier. */
+  readonly datasetId: string;
+  /** Owning tenant. */
+  readonly tenantId: TenantId;
+  /** Version of the dataset (semver). */
+  readonly version: string;
+  /** Fact type stored in this dataset (matches memory.schema.json Fact.type). */
+  readonly factType: string;
+  /** Number of items in this version. */
+  readonly count: number;
+  /** When this version was created. */
+  readonly createdAt: Timestamp;
+}

package/src/result.test-d.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { describe, expectTypeOf, test } from 'vitest';
+import type { ErrOf, OkOf, Result } from './result.js';
+
+describe('Result<T, E>', () => {
+  test('kind narrows to the corresponding member', () => {
+    // Wrapped in a function so TS keeps the full Result<number, string> type
+    // rather than narrowing to the assigned object literal at a `const` binding.
+    function inspect(r: Result<number, string>): void {
+      if (r.kind === 'ok') {
+        expectTypeOf(r.value).toEqualTypeOf<number>();
+        // The err member is not accessible in the ok branch.
+        // @ts-expect-error — 'error' is only on the err member.
+        const _e = r.error;
+      } else {
+        expectTypeOf(r.error).toEqualTypeOf<string>();
+        // Symmetric: 'value' is not accessible in the err branch.
+        // @ts-expect-error — 'value' is only on the ok member.
+        const _v = r.value;
+      }
+    }
+    inspect({ kind: 'ok', value: 42 });
+    inspect({ kind: 'err', error: 'bad' });
+  });
+
+  test('Result cannot be constructed without a kind tag', () => {
+    // @ts-expect-error — missing 'kind' discriminator.
+    const _bad: Result<number, string> = { value: 1 };
+    // @ts-expect-error — 'kind' must be 'ok' or 'err'.
+    const _bad2: Result<number, string> = { kind: 'maybe', value: 1 };
+  });
+
+  test('OkOf extracts the success type', () => {
+    type R = Result<{ id: string }, Error>;
+    expectTypeOf<OkOf<R>>().toEqualTypeOf<{ id: string }>();
+  });
+
+  test('ErrOf extracts the error type', () => {
+    type R = Result<number, { code: 'timeout' } | { code: 'refused' }>;
+    expectTypeOf<ErrOf<R>>().toEqualTypeOf<{ code: 'timeout' } | { code: 'refused' }>();
+  });
+
+  test('OkOf / ErrOf return never for non-Result inputs', () => {
+    expectTypeOf<OkOf<string>>().toEqualTypeOf<never>();
+    expectTypeOf<ErrOf<{ foo: 'bar' }>>().toEqualTypeOf<never>();
+  });
+
+  test('values are readonly by declaration', () => {
+    function mutate(r: Result<number, string>): void {
+      if (r.kind === 'ok') {
+        // @ts-expect-error — value is readonly.
+        r.value = 2;
+      }
+    }
+    mutate({ kind: 'ok', value: 1 });
+  });
+});

package/src/result.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * A discriminated-union result type. Preferred over throwing for boundary
+ * operations where the caller must handle both success and failure explicitly.
+ *
+ * Every member carries a runtime `kind` tag so consumers can narrow via
+ * `if (r.kind === 'ok') { ... }`. This is the codebase's standard shape;
+ * do not invent parallel Ok/Err representations.
+ *
+ * @example
+ * function loadSchema(path: string): Result<Schema, SchemaLoadError> {
+ *   try {
+ *     return { kind: 'ok', value: parse(readFileSync(path)) };
+ *   } catch (cause) {
+ *     return { kind: 'err', error: { code: 'load-failed', path, cause } };
+ *   }
+ * }
+ *
+ * const r = loadSchema('./flow.schema.json');
+ * if (r.kind === 'ok') { use(r.value); } else { handle(r.error); }
+ */
+export type Result<T, E> =
+  | { readonly kind: 'ok'; readonly value: T }
+  | { readonly kind: 'err'; readonly error: E };
+
+/**
+ * Extract the success type from a Result.
+ *
+ * @example
+ * type Value = OkOf<Result<number, string>>; // number
+ */
+export type OkOf<R> = R extends { readonly kind: 'ok'; readonly value: infer T } ? T : never;
+
+/**
+ * Extract the error type from a Result.
+ *
+ * @example
+ * type Failure = ErrOf<Result<number, string>>; // string
+ */
+export type ErrOf<R> = R extends { readonly kind: 'err'; readonly error: infer E } ? E : never;

package/src/temporal.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Brand } from './ids.js';
+
+/**
+ * An ISO 8601 timestamp string, always UTC (trailing 'Z').
+ *
+ * Example: '2026-09-16T14:23:45.123Z'
+ *
+ * Kept as a string rather than a Date object for two reasons:
+ *   1. JSON-serializable by construction — no `.toISOString()` traps at boundaries.
+ *   2. Deterministic ordering by lexicographic sort, which matches temporal order
+ *      for well-formed ISO 8601 UTC strings. Anything that orders records by
+ *      timestamp (e.g. run replay) relies on this.
+ */
+export type Timestamp = Brand<string, 'Timestamp'>;
+
+/**
+ * A duration expressed in milliseconds.
+ *
+ * Branded to distinguish from arbitrary numbers at call sites like
+ * `wait(500)` vs `wait(500 as DurationMs)`.
+ */
+export type DurationMs = Brand<number, 'DurationMs'>;
+
+/**
+ * A duration expressed as an ISO 8601 duration string.
+ *
+ * Example: 'PT30S' (30 seconds), 'PT2H' (2 hours), 'P1D' (1 day).
+ *
+ * Preferred over `DurationMs` in declarative artifacts (task flows, retention
+ * policies) because it's human-readable and unambiguous across serialization.
+ */
+export type IsoDuration = Brand<string, 'IsoDuration'>;

package/src/version.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Brand } from './ids.js';
+
+/**
+ * A semver version string (major.minor.patch, with optional pre-release).
+ *
+ * Regex convention: `^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$`.
+ *
+ * Used for:
+ *   - Artifact versions (flow.version, policy.version, provenance.version).
+ *   - Pack manifest versions.
+ *   - Schema versions in `$comment: "schema-version: X.Y.Z"`.
+ *
+ * The brand prevents mixing free-form strings with validated semver values.
+ */
+export type Semver = Brand<string, 'Semver'>;
+
+/**
+ * Major version number extracted from a semver, used for schema $id path segments.
+ *
+ * Convention: `1`, `2`, `3` (positive integer). No `v` prefix — the `v` is added
+ * by the URL scheme (`/v1/flow.schema.json`), not part of the value.
+ */
+export type SchemaMajor = Brand<number, 'SchemaMajor'>;
+
+/**
+ * Version-pinned artifact reference. Combines an artifact id with an exact
+ * semver, so replays and audit trails always know which version was in force.
+ *
+ * @example
+ * const flowRef: VersionedRef<FlowId> = {
+ *   id: 'acme.contract-review' as FlowId,
+ *   version: '1.2.3' as Semver,
+ * };
+ */
+export interface VersionedRef<Id extends string> {
+  readonly id: Id;
+  readonly version: Semver;
+}