@kindgi/types 0.0.0-bootstrap.0 → 0.1.0

package/dist/ids.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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'>;
+/**
+ * Validated `EnvName` factory. Returns `null` on any grammar violation
+ * (uppercase, underscore, dot, slash, non-ASCII, empty, >63 chars).
+ */
+export declare function makeEnvName(raw: string): EnvName | null;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

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

package/dist/ids.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+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) {
+    if (typeof raw !== 'string')
+        return null;
+    if (!ENV_NAME_GRAMMAR.test(raw))
+        return null;
+    return raw;
+}
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAqNjC,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AAElD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,GAAc,CAAC;AACxB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+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';
+export { makeEnvName } from './ids.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,mBAAmB,aAAa,CAAC;AACjC,mBAAmB,WAAW,CAAC;AAC/B,mBAAmB,UAAU,CAAC;AAC9B,mBAAmB,WAAW,CAAC;AAC/B,mBAAmB,aAAa,CAAC;AACjC,mBAAmB,eAAe,CAAC;AACnC,mBAAmB,cAAc,CAAC;AAKlC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+// 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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAUjC,uEAAuE;AACvE,qEAAqE;AACrE,+DAA+D;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/refs.d.ts

@@ -0,0 +1,58 @@
+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;
+}
+//# sourceMappingURL=refs.d.ts.map

package/dist/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,iBAAiB;IACjB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B"}

package/dist/refs.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=refs.js.map

package/dist/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/result.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7F;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC"}

package/dist/result.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/temporal.d.ts

@@ -0,0 +1,30 @@
+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'>;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC"}

package/dist/temporal.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=temporal.js.map

package/dist/temporal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.js","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/version.d.ts

@@ -0,0 +1,36 @@
+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;
+}
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEvD;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,MAAM;IAC7C,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/version.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/package.json

@@ -1,7 +1,49 @@
 {
   "name": "@kindgi/types",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "Foundational TypeScript types shared across Kindgi. Branded IDs, timestamps, hashes, refs, Result, list filter / page shapes. Zero runtime dependencies; the only runtime export is the makeEnvName validator.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/types"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/types#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "SPEC.md",
+    "type-manifest.json"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --typecheck --typecheck.only --passWithNoTests",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/filter.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Brand } from './ids.js';
+import type { Timestamp } from './temporal.js';
+
+/**
+ * Opaque pagination cursor. Producers return a `Cursor`; consumers pass
+ * it back verbatim to the next list call. The value is implementation-
+ * defined (usually a timestamp or opaque token) — callers must not
+ * parse or construct one by hand.
+ */
+export type Cursor = Brand<string, 'Cursor'>;
+
+/**
+ * Shared list-filter shape. List inputs extend this (e.g. the team and
+ * project bindings in `@kindgi/platform`) so resources share one
+ * facet-filter shape.
+ *
+ * `TStatus` narrows the `status` field per-resource (e.g. the
+ * `ApprovalStatus`, `FixProposalStatus` and `ObservationStatus` unions
+ * in `@kindgi/api`).
+ *
+ * All fields are optional. A caller can pass an empty `Filter` to get
+ * the default page.
+ */
+export interface Filter<TStatus extends string = string> {
+  /**
+   * Filter to one status or a set of statuses. The resource-specific
+   * input type narrows TStatus so consumers get autocomplete on the
+   * allowed values.
+   */
+  readonly status?: TStatus | readonly TStatus[];
+  /**
+   * Lower bound on the resource's canonical timestamp — typically
+   * `createdAt` or `observedAt`. Inclusive. Absent = no lower bound.
+   */
+  readonly since?: Timestamp;
+  /**
+   * Upper bound on the resource's canonical timestamp. Inclusive.
+   * Absent = no upper bound.
+   */
+  readonly until?: Timestamp;
+  /**
+   * Max items to return. Producers clamp to a resource-specific ceiling
+   * (typically 500). Default page size is producer-defined.
+   */
+  readonly limit?: number;
+  /** Opaque cursor from a prior list call's `nextCursor` field. */
+  readonly cursor?: Cursor;
+}
+
+/**
+ * Shared list-result envelope. List producers that use it return
+ * `{ items, nextCursor? }`. Consumers keep calling with `cursor:
+ * result.nextCursor` until it's absent.
+ *
+ * `truncated: true` explicitly signals "more items exist beyond the
+ * cursor" for aggregators that don't paginate but should still know
+ * they missed data.
+ */
+export interface Page<T> {
+  readonly items: readonly T[];
+  readonly nextCursor?: Cursor;
+  readonly truncated?: boolean;
+}

package/src/hash.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Brand } from './ids.js';
+
+/**
+ * A content-addressed hash of a payload, formatted as `<algo>:<hex>`.
+ *
+ * Current supported algorithms:
+ *   - `sha256:<64 hex chars>`
+ *
+ * Meant for content addressing: tamper-evident provenance node content,
+ * blob dedup at ingest, memory LogEntry / Fact content hashes.
+ *
+ * The prefix is significant: consumers must reject hashes without a recognized
+ * algorithm prefix, so future migration to sha3 or blake3 is non-breaking.
+ */
+export type ContentHash = Brand<string, 'ContentHash'>;
+
+/**
+ * An Ed25519 signature over some canonical serialization, base64-encoded.
+ *
+ * Format is padded base64 (RFC 4648 §4). No URL-safe variants — canonical form
+ * for interoperability with signing tools.
+ */
+export type SignatureValue = Brand<string, 'SignatureValue'>;
+
+/**
+ * Identifier for a signing key in provider-qualified form. Opaque to Kindgi;
+ * interpreted by whichever key provider resolves it. (Keys held in a
+ * `SigningKeyBinding` from `@kindgi/crypto` are addressed by `SigningKeyId`.)
+ *
+ * Convention: `<provider>:<key-name>` (e.g. `ed25519-local:tenant-abc-v1`,
+ * `hsm:pkcs11:slot-3:key-42`, `kms:aws:arn:aws:kms:...`). Consumers should
+ * treat this string as opaque and let the provider resolve it.
+ */
+export type KeyId = Brand<string, 'KeyId'>;