@rohzzn/uidna-schema 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@rohzzn/uidna-schema` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package
+follows semantic versioning. `dnaVersion` inside a document tracks this
+package's version.
+
+## [0.1.0] - 2026-10-13
+
+### Added
+
+- First published UI DNA document schema (`dnaVersion` 0.1.0).
+- Provenance envelope (`measured | observed | inferred | unknown`) with the
+  rule that `inferred` values come only from the `agent` source and `unknown`
+  values carry a reason instead of a value.
+- Top-level sections: `target`, `app`, `states`, `components`, `visual`,
+  `behavior`, `assets`, `limitations`, `evidence`, `annotations` (the log of
+  agent patches applied through `annotate_dna`).
+- `validateUiDna`, `parseUiDna`, `isUiDna` helpers and a generated JSON Schema
+  at `@rohzzn/uidna-schema/ui-dna.schema.json`.
+- Complete example document built from Fixture A (`fixtures/a-marketing`).

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @rohzzn/uidna-schema
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The UI DNA document schema. A UI DNA document describes a user interface the
+way an engineer would need it described to rebuild it: pages and navigation,
+observed states and the transitions between them, component candidates with
+their instances, visual tokens with the measurements that support them, layout
+constraints per node, observed behavior, assets and, just as importantly, what
+could not be observed.
+
+Every measured or inferred value is wrapped in a provenance envelope that says
+how it was obtained, from which state and viewport, with which evidence and
+with what confidence. Values that are not known are marked `unknown` with a
+reason. They are never empty strings, zeros or `false`.
+
+The schema is framework neutral. It contains no React, Tailwind or other
+output-framework terms, so any generator or tool can consume it.
+
+```ts
+import { parseUiDna, validateUiDna, UI_DNA_VERSION } from '@rohzzn/uidna-schema';
+
+const result = validateUiDna(JSON.parse(text));
+if (!result.success) console.error(result.error.issues);
+```
+
+The JSON Schema is published at `@rohzzn/uidna-schema/ui-dna.schema.json`. The full
+reference lives in `docs/ui-dna.md` in the UI DNA repository.

package/dist/scripts/json-schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/json-schema.js

@@ -0,0 +1,27 @@
+/**
+ * Generates `dist/ui-dna.schema.json` from the Zod schema. Run after `tsc`.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { UiDnaDocumentStructureSchema, UI_DNA_VERSION } from '../src/schema.js';
+const here = dirname(fileURLToPath(import.meta.url));
+// When run from dist/scripts/, the package root is two levels up; from scripts/ it is one.
+const packageRoot = here.endsWith(join('dist', 'scripts')) ? join(here, '..', '..') : join(here, '..');
+const outDir = join(packageRoot, 'dist');
+const jsonSchema = z.toJSONSchema(UiDnaDocumentStructureSchema, {
+    target: 'draft-2020-12',
+    unrepresentable: 'any',
+    io: 'input',
+});
+const withMeta = {
+    $id: `https://uidna.dev/schema/ui-dna/${UI_DNA_VERSION}/ui-dna.schema.json`,
+    title: 'UI DNA document',
+    description: 'Describes a user interface down to the token, the component and the state transition, with provenance on every value. Cross-reference rules (state, page and component ids must resolve) are enforced by the Zod schema and are not expressible here.',
+    ...jsonSchema,
+};
+await mkdir(outDir, { recursive: true });
+await writeFile(join(outDir, 'ui-dna.schema.json'), JSON.stringify(withMeta, null, 2) + '\n', 'utf8');
+console.log(`wrote ${join(outDir, 'ui-dna.schema.json')}`);
+//# sourceMappingURL=json-schema.js.map

package/dist/scripts/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../../scripts/json-schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEhF,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,2FAA2F;AAC3F,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACvG,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAEzC,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,4BAA4B,EAAE;IAC9D,MAAM,EAAE,eAAe;IACvB,eAAe,EAAE,KAAK;IACtB,EAAE,EAAE,OAAO;CACZ,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG;IACf,GAAG,EAAE,mCAAmC,cAAc,qBAAqB;IAC3E,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,uPAAuP;IACzP,GAAG,UAAU;CACd,CAAC;AAEF,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AACtG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAAE,CAAC,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @rohzzn/uidna-schema — the UI DNA document schema.
+ *
+ * A UI DNA document describes a user interface down to the token, the
+ * component and the state transition, with provenance on every value.
+ */
+import type { z } from 'zod';
+import type { UiDnaDocument } from './schema.js';
+export * from './provenance.js';
+export * from './schema.js';
+/** Result of `validateUiDna`: either a validated document or the Zod error. */
+export type UiDnaValidation = z.ZodSafeParseResult<UiDnaDocument>;
+/** Validate an unknown value as a UI DNA document. Never throws. */
+export declare function validateUiDna(input: unknown): UiDnaValidation;
+/** Parse an unknown value as a UI DNA document, throwing a `ZodError` on failure. */
+export declare function parseUiDna(input: unknown): UiDnaDocument;
+/** Type guard: true when `input` is a valid UI DNA document. */
+export declare function isUiDna(input: unknown): input is UiDnaDocument;
+/** Human-readable list of validation issues, one per line. */
+export declare function formatIssues(validation: UiDnaValidation): string[];
+/** True when a document's `dnaVersion` is one this package can read (same major version). */
+export declare function isCompatibleVersion(dnaVersion: string): boolean;

package/dist/src/index.js

@@ -0,0 +1,28 @@
+import { UiDnaDocumentSchema, UI_DNA_VERSION } from './schema.js';
+export * from './provenance.js';
+export * from './schema.js';
+/** Validate an unknown value as a UI DNA document. Never throws. */
+export function validateUiDna(input) {
+    return UiDnaDocumentSchema.safeParse(input);
+}
+/** Parse an unknown value as a UI DNA document, throwing a `ZodError` on failure. */
+export function parseUiDna(input) {
+    return UiDnaDocumentSchema.parse(input);
+}
+/** Type guard: true when `input` is a valid UI DNA document. */
+export function isUiDna(input) {
+    return UiDnaDocumentSchema.safeParse(input).success;
+}
+/** Human-readable list of validation issues, one per line. */
+export function formatIssues(validation) {
+    if (validation.success)
+        return [];
+    return validation.error.issues.map((issue) => `${issue.path.map(String).join('.') || '<root>'}: ${issue.message}`);
+}
+/** True when a document's `dnaVersion` is one this package can read (same major version). */
+export function isCompatibleVersion(dnaVersion) {
+    const [docMajor] = dnaVersion.split('.');
+    const [ourMajor] = UI_DNA_VERSION.split('.');
+    return docMajor !== undefined && docMajor === ourMajor;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlE,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAK5B,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AACtD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,UAA2B;IACtD,IAAI,UAAU,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;AACrH,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,QAAQ,CAAC;AACzD,CAAC"}

package/dist/src/provenance.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Provenance envelope. Every measured or inferred value in a UI DNA document
+ * is wrapped with how it was obtained. Missing evidence is `unknown` with a
+ * reason; it is never an empty string, zero or `false`.
+ */
+import { z } from 'zod';
+/** The four provenance kinds. Measured beats observed, observed beats inferred. */
+export declare const PROVENANCE_KINDS: readonly ["measured", "observed", "inferred", "unknown"];
+/** Where a value came from. `agent` is the only source allowed for `inferred`. */
+export declare const PROVENANCE_SOURCES: readonly ["computed-style", "bounding-box", "a11y-tree", "screenshot", "interaction", "network", "agent"];
+/** Instrument sources: everything except `agent`. */
+export declare const INSTRUMENT_SOURCES: readonly ["computed-style", "bounding-box", "a11y-tree", "screenshot", "interaction", "network"];
+/** Viewport size in CSS pixels. */
+export declare const ViewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strict>;
+export type Viewport = z.infer<typeof ViewportSchema>;
+/** Provenance of a value measured directly by the instrument. */
+export declare const MeasuredProvenanceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"measured">;
+    source: z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+}, z.core.$strict>;
+export type MeasuredProvenance = z.infer<typeof MeasuredProvenanceSchema>;
+/** Provenance of a value observed by the instrument (an interaction outcome, a visual change) rather than measured as a number. */
+export declare const ObservedProvenanceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"observed">;
+    source: z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+}, z.core.$strict>;
+export type ObservedProvenance = z.infer<typeof ObservedProvenanceSchema>;
+/** Provenance of a value written by the host agent through `annotate_dna`. Only `agent` may infer. */
+export declare const InferredProvenanceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"inferred">;
+    source: z.ZodLiteral<"agent">;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    basedOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type InferredProvenance = z.infer<typeof InferredProvenanceSchema>;
+/** Provenance of a value that could not be obtained. Carries the reason instead of a value. */
+export declare const UnknownProvenanceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"unknown">;
+    reason: z.ZodString;
+    source: z.ZodOptional<z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type UnknownProvenance = z.infer<typeof UnknownProvenanceSchema>;
+/** Provenance for values that exist (measured, observed or inferred). */
+export declare const KnownProvenanceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"measured">;
+    source: z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"observed">;
+    source: z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"inferred">;
+    source: z.ZodLiteral<"agent">;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    basedOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>], "kind">;
+export type KnownProvenance = z.infer<typeof KnownProvenanceSchema>;
+/** Any provenance. */
+export declare const ProvenanceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"measured">;
+    source: z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"observed">;
+    source: z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"inferred">;
+    source: z.ZodLiteral<"agent">;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodISODateTime;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    basedOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unknown">;
+    reason: z.ZodString;
+    source: z.ZodOptional<z.ZodEnum<{
+        "computed-style": "computed-style";
+        "bounding-box": "bounding-box";
+        "a11y-tree": "a11y-tree";
+        screenshot: "screenshot";
+        interaction: "interaction";
+        network: "network";
+    }>>;
+    stateId: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    evidenceId: z.ZodOptional<z.ZodString>;
+    capturedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>], "kind">;
+export type Provenance = z.infer<typeof ProvenanceSchema>;
+export type ProvenanceKind = Provenance['kind'];
+export type ProvenanceSource = (typeof PROVENANCE_SOURCES)[number];
+/**
+ * Wrap a value schema in the provenance envelope. A known value carries a
+ * known provenance; an unknown value is `null` with an `unknown` provenance
+ * that explains why. An `annotation` lets the agent attach its own reading
+ * next to the measured one without overwriting it.
+ */
+export declare function attributed<T extends z.ZodType>(value: T): z.ZodUnion<readonly [z.ZodObject<{
+    value: T;
+    provenance: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"measured">;
+        source: z.ZodEnum<{
+            "computed-style": "computed-style";
+            "bounding-box": "bounding-box";
+            "a11y-tree": "a11y-tree";
+            screenshot: "screenshot";
+            interaction: "interaction";
+            network: "network";
+        }>;
+        stateId: z.ZodOptional<z.ZodString>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        evidenceId: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodISODateTime;
+        confidence: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"observed">;
+        source: z.ZodEnum<{
+            "computed-style": "computed-style";
+            "bounding-box": "bounding-box";
+            "a11y-tree": "a11y-tree";
+            screenshot: "screenshot";
+            interaction: "interaction";
+            network: "network";
+        }>;
+        stateId: z.ZodOptional<z.ZodString>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        evidenceId: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodISODateTime;
+        confidence: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"inferred">;
+        source: z.ZodLiteral<"agent">;
+        stateId: z.ZodOptional<z.ZodString>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        evidenceId: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodISODateTime;
+        confidence: z.ZodNumber;
+        rationale: z.ZodOptional<z.ZodString>;
+        basedOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>], "kind">;
+    annotation: z.ZodOptional<z.ZodObject<{
+        value: T;
+        provenance: z.ZodObject<{
+            kind: z.ZodLiteral<"inferred">;
+            source: z.ZodLiteral<"agent">;
+            stateId: z.ZodOptional<z.ZodString>;
+            viewport: z.ZodOptional<z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>>;
+            evidenceId: z.ZodOptional<z.ZodString>;
+            capturedAt: z.ZodISODateTime;
+            confidence: z.ZodNumber;
+            rationale: z.ZodOptional<z.ZodString>;
+            basedOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    value: z.ZodNull;
+    provenance: z.ZodObject<{
+        kind: z.ZodLiteral<"unknown">;
+        reason: z.ZodString;
+        source: z.ZodOptional<z.ZodEnum<{
+            "computed-style": "computed-style";
+            "bounding-box": "bounding-box";
+            "a11y-tree": "a11y-tree";
+            screenshot: "screenshot";
+            interaction: "interaction";
+            network: "network";
+        }>>;
+        stateId: z.ZodOptional<z.ZodString>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        evidenceId: z.ZodOptional<z.ZodString>;
+        capturedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    annotation: z.ZodOptional<z.ZodObject<{
+        value: T;
+        provenance: z.ZodObject<{
+            kind: z.ZodLiteral<"inferred">;
+            source: z.ZodLiteral<"agent">;
+            stateId: z.ZodOptional<z.ZodString>;
+            viewport: z.ZodOptional<z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>>;
+            evidenceId: z.ZodOptional<z.ZodString>;
+            capturedAt: z.ZodISODateTime;
+            confidence: z.ZodNumber;
+            rationale: z.ZodOptional<z.ZodString>;
+            basedOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+/** TypeScript shape of an attributed value. */
+export type Attributed<T> = {
+    value: T;
+    provenance: KnownProvenance;
+    annotation?: {
+        value: T;
+        provenance: InferredProvenance;
+    };
+} | {
+    value: null;
+    provenance: UnknownProvenance;
+    annotation?: {
+        value: T;
+        provenance: InferredProvenance;
+    };
+};
+/** Context shared by many measured values of one capture. */
+export interface ProvenanceContext {
+    stateId?: string;
+    viewport?: Viewport;
+    evidenceId?: string;
+    capturedAt: string;
+}
+/** Build a measured value. */
+export declare function measured<T>(value: T, source: (typeof INSTRUMENT_SOURCES)[number], context: ProvenanceContext, confidence?: number): Attributed<T>;
+/** Build an observed value. */
+export declare function observed<T>(value: T, source: (typeof INSTRUMENT_SOURCES)[number], context: ProvenanceContext, confidence?: number): Attributed<T>;
+/** Build an inferred (agent-written) value. */
+export declare function inferred<T>(value: T, context: ProvenanceContext & {
+    rationale?: string;
+    basedOn?: string[];
+}, confidence: number): Attributed<T>;
+/** Build an unknown value with a reason. */
+export declare function unknown<T = never>(reason: string, context?: Partial<ProvenanceContext> & {
+    source?: (typeof INSTRUMENT_SOURCES)[number];
+}): Attributed<T>;
+/** True when the attributed value is known (not `unknown`). */
+export declare function isKnown<T>(attr: Attributed<T>): attr is Extract<Attributed<T>, {
+    value: T;
+}>;
+/** The agent's annotation when present, otherwise the instrument's value. */
+export declare function effectiveValue<T>(attr: Attributed<T>): T | null;