@rohzzn/uidna-schema 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,163 @@
1
+ /**
2
+ * Provenance envelope. Every measured or inferred value in a UI DNA document
3
+ * is wrapped with how it was obtained. Missing evidence is `unknown` with a
4
+ * reason; it is never an empty string, zero or `false`.
5
+ */
6
+ import { z } from 'zod';
7
+ /** The four provenance kinds. Measured beats observed, observed beats inferred. */
8
+ export const PROVENANCE_KINDS = ['measured', 'observed', 'inferred', 'unknown'];
9
+ /** Where a value came from. `agent` is the only source allowed for `inferred`. */
10
+ export const PROVENANCE_SOURCES = [
11
+ 'computed-style',
12
+ 'bounding-box',
13
+ 'a11y-tree',
14
+ 'screenshot',
15
+ 'interaction',
16
+ 'network',
17
+ 'agent',
18
+ ];
19
+ /** Instrument sources: everything except `agent`. */
20
+ export const INSTRUMENT_SOURCES = [
21
+ 'computed-style',
22
+ 'bounding-box',
23
+ 'a11y-tree',
24
+ 'screenshot',
25
+ 'interaction',
26
+ 'network',
27
+ ];
28
+ /** Viewport size in CSS pixels. */
29
+ export const ViewportSchema = z.strictObject({
30
+ width: z.number().int().positive(),
31
+ height: z.number().int().positive(),
32
+ });
33
+ const IsoDateTime = z.iso.datetime({ offset: true });
34
+ const Confidence = z.number().min(0).max(1);
35
+ /** Provenance of a value measured directly by the instrument. */
36
+ export const MeasuredProvenanceSchema = z.strictObject({
37
+ kind: z.literal('measured'),
38
+ source: z.enum(INSTRUMENT_SOURCES),
39
+ stateId: z.string().optional(),
40
+ viewport: ViewportSchema.optional(),
41
+ evidenceId: z.string().optional(),
42
+ capturedAt: IsoDateTime,
43
+ confidence: Confidence,
44
+ });
45
+ /** Provenance of a value observed by the instrument (an interaction outcome, a visual change) rather than measured as a number. */
46
+ export const ObservedProvenanceSchema = z.strictObject({
47
+ kind: z.literal('observed'),
48
+ source: z.enum(INSTRUMENT_SOURCES),
49
+ stateId: z.string().optional(),
50
+ viewport: ViewportSchema.optional(),
51
+ evidenceId: z.string().optional(),
52
+ capturedAt: IsoDateTime,
53
+ confidence: Confidence,
54
+ });
55
+ /** Provenance of a value written by the host agent through `annotate_dna`. Only `agent` may infer. */
56
+ export const InferredProvenanceSchema = z.strictObject({
57
+ kind: z.literal('inferred'),
58
+ source: z.literal('agent'),
59
+ stateId: z.string().optional(),
60
+ viewport: ViewportSchema.optional(),
61
+ evidenceId: z.string().optional(),
62
+ capturedAt: IsoDateTime,
63
+ confidence: Confidence,
64
+ /** Why the agent believes this. */
65
+ rationale: z.string().optional(),
66
+ /** Evidence ids the inference rests on. */
67
+ basedOn: z.array(z.string()).optional(),
68
+ });
69
+ /** Provenance of a value that could not be obtained. Carries the reason instead of a value. */
70
+ export const UnknownProvenanceSchema = z.strictObject({
71
+ kind: z.literal('unknown'),
72
+ reason: z.string().min(1),
73
+ source: z.enum(INSTRUMENT_SOURCES).optional(),
74
+ stateId: z.string().optional(),
75
+ viewport: ViewportSchema.optional(),
76
+ evidenceId: z.string().optional(),
77
+ capturedAt: IsoDateTime.optional(),
78
+ });
79
+ /** Provenance for values that exist (measured, observed or inferred). */
80
+ export const KnownProvenanceSchema = z.discriminatedUnion('kind', [
81
+ MeasuredProvenanceSchema,
82
+ ObservedProvenanceSchema,
83
+ InferredProvenanceSchema,
84
+ ]);
85
+ /** Any provenance. */
86
+ export const ProvenanceSchema = z.discriminatedUnion('kind', [
87
+ MeasuredProvenanceSchema,
88
+ ObservedProvenanceSchema,
89
+ InferredProvenanceSchema,
90
+ UnknownProvenanceSchema,
91
+ ]);
92
+ /**
93
+ * Wrap a value schema in the provenance envelope. A known value carries a
94
+ * known provenance; an unknown value is `null` with an `unknown` provenance
95
+ * that explains why. An `annotation` lets the agent attach its own reading
96
+ * next to the measured one without overwriting it.
97
+ */
98
+ export function attributed(value) {
99
+ const annotation = z.strictObject({ value, provenance: InferredProvenanceSchema });
100
+ return z.union([
101
+ z.strictObject({ value, provenance: KnownProvenanceSchema, annotation: annotation.optional() }),
102
+ z.strictObject({ value: z.null(), provenance: UnknownProvenanceSchema, annotation: annotation.optional() }),
103
+ ]);
104
+ }
105
+ function withContext(kind, source, context, confidence) {
106
+ const provenance = {
107
+ kind,
108
+ source,
109
+ capturedAt: context.capturedAt,
110
+ confidence,
111
+ ...(context.stateId === undefined ? {} : { stateId: context.stateId }),
112
+ ...(context.viewport === undefined ? {} : { viewport: context.viewport }),
113
+ ...(context.evidenceId === undefined ? {} : { evidenceId: context.evidenceId }),
114
+ };
115
+ return provenance;
116
+ }
117
+ /** Build a measured value. */
118
+ export function measured(value, source, context, confidence = 1) {
119
+ return { value, provenance: withContext('measured', source, context, confidence) };
120
+ }
121
+ /** Build an observed value. */
122
+ export function observed(value, source, context, confidence = 1) {
123
+ return { value, provenance: withContext('observed', source, context, confidence) };
124
+ }
125
+ /** Build an inferred (agent-written) value. */
126
+ export function inferred(value, context, confidence) {
127
+ const provenance = {
128
+ kind: 'inferred',
129
+ source: 'agent',
130
+ capturedAt: context.capturedAt,
131
+ confidence,
132
+ ...(context.stateId === undefined ? {} : { stateId: context.stateId }),
133
+ ...(context.viewport === undefined ? {} : { viewport: context.viewport }),
134
+ ...(context.evidenceId === undefined ? {} : { evidenceId: context.evidenceId }),
135
+ ...(context.rationale === undefined ? {} : { rationale: context.rationale }),
136
+ ...(context.basedOn === undefined ? {} : { basedOn: context.basedOn }),
137
+ };
138
+ return { value, provenance };
139
+ }
140
+ /** Build an unknown value with a reason. */
141
+ export function unknown(reason, context = {}) {
142
+ const provenance = {
143
+ kind: 'unknown',
144
+ reason,
145
+ ...(context.source === undefined ? {} : { source: context.source }),
146
+ ...(context.stateId === undefined ? {} : { stateId: context.stateId }),
147
+ ...(context.viewport === undefined ? {} : { viewport: context.viewport }),
148
+ ...(context.evidenceId === undefined ? {} : { evidenceId: context.evidenceId }),
149
+ ...(context.capturedAt === undefined ? {} : { capturedAt: context.capturedAt }),
150
+ };
151
+ return { value: null, provenance };
152
+ }
153
+ /** True when the attributed value is known (not `unknown`). */
154
+ export function isKnown(attr) {
155
+ return attr.provenance.kind !== 'unknown';
156
+ }
157
+ /** The agent's annotation when present, otherwise the instrument's value. */
158
+ export function effectiveValue(attr) {
159
+ if (attr.annotation)
160
+ return attr.annotation.value;
161
+ return attr.value;
162
+ }
163
+ //# sourceMappingURL=provenance.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../src/provenance.ts"],"names":[],"mappings":"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"}