@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/templates/profile.mjs

@@ -0,0 +1,225 @@
+import fs from 'node:fs'
+import { createHash } from 'node:crypto'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs'
+import { validateDecisionRequest, validateDecisionResult } from '../decisions/contracts.mjs'
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-template-profile.v1.schema.json', import.meta.url), 'utf8'))
+const shapes = Object.fromEntries(Object.keys(schema.$defs).map(kind => [kind, {
+  $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}`,
+}]))
+const forbidden = new Set(['__proto__', 'prototype', 'constructor'])
+const referenceKinds = new Set(Object.keys(schema.$defs).filter(kind => kind.endsWith('Ref')))
+
+// Inspect descriptors before traversing untrusted values; no getters or toJSON.
+// All public entry points snapshot once before relational or hash checks.
+function snapshot(input) {
+  const ancestors = new Set()
+  let nodes = 0, bytes = 0
+  function copy(value, depth) {
+    if (++nodes > 20000 || depth > 24) throw new TypeError('template input limit')
+    if (value === null || typeof value === 'boolean' || typeof value === 'string' || typeof value === 'number' && Number.isFinite(value)) {
+      if (typeof value === 'string' && value.length > 1048576) throw new TypeError('template input limit')
+      bytes += Buffer.byteLength(JSON.stringify(value))
+      if (bytes > 1048576) throw new TypeError('template input limit')
+      return value
+    }
+    if (!value || typeof value !== 'object' || ancestors.has(value)) throw new TypeError('template input is not JSON')
+    const array = Array.isArray(value), proto = Object.getPrototypeOf(value)
+    if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) throw new TypeError('template input prototype')
+    const descriptors = Object.getOwnPropertyDescriptors(value), keys = Reflect.ownKeys(descriptors)
+    if (keys.some(key => typeof key !== 'string' || forbidden.has(key))) throw new TypeError('template input key')
+    ancestors.add(value)
+    const result = array ? [] : {}
+    if (array && (descriptors.length.value > 20000 || keys.length !== descriptors.length.value + 1)) throw new TypeError('template array shape')
+    for (const key of keys) {
+      if (array && key === 'length') continue
+      const d = descriptors[key]
+      if (!Object.hasOwn(d, 'value') || !d.enumerable || array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new TypeError('template input descriptor')
+      bytes += Buffer.byteLength(key) + 4
+      if (bytes > 1048576) throw new TypeError('template input limit')
+      result[key] = copy(d.value, depth + 1)
+    }
+    if (array && result.length !== descriptors.length.value) throw new TypeError('template sparse array')
+    ancestors.delete(value)
+    return result
+  }
+  return copy(input, 0)
+}
+
+function shape(kind, value, errors) {
+  const invalid = validateJsonSchema(shapes[kind], value).length > 0
+  if (invalid) errors.push(`invalid ${kind} shape`)
+  return !invalid
+}
+function same(a, b) { return canonicalize(a) === canonicalize(b) }
+function unique(items, key, errors, label) {
+  if (new Set(items.map(key)).size !== items.length) errors.push(`duplicate ${label}`)
+}
+function refFor(kind, id, version, document) {
+  if (!referenceKinds.has(kind)) throw new TypeError('unsupported reference kind')
+  const domain = { schema: 'atelier-template-digest@v1', kind, id, version, document }
+  const digest = `sha256:${createHash('sha256').update(canonicalize(domain)).digest('hex')}`
+  const ref = { kind, id, version, digest }
+  if (validateJsonSchema(shapes[kind], ref).length) throw new TypeError('invalid reference identity')
+  return ref
+}
+
+/** Content identity only; neither signature verification nor owner acceptance. */
+export function templateReference(kind, id, version, document) {
+  const value = snapshot({ kind, id, version, document })
+  return refFor(value.kind, value.id, value.version, value.document)
+}
+
+function run(stage, input, inspect) {
+  const errors = [], diagnostics = []
+  try { inspect(snapshot(input), errors, diagnostics) }
+  catch { errors.push('expected bounded plain JSON and supported reference identity') }
+  return { ok: errors.length === 0, stage, errors: [...new Set(errors)], diagnostics,
+    authority: 'structural-only', executionAuthority: false, publicationAuthority: false }
+}
+
+function definition(value, errors) {
+  if (!shape('definition', value, errors)) return false
+  unique(value.semanticRoles, x => x.id, errors, 'semantic role')
+  unique(value.surfaceRoles, x => x.id, errors, 'surface role')
+  unique(value.carriers, x => x.id, errors, 'carrier')
+  unique(value.extensions, x => x.namespace, errors, 'extension namespace')
+  unique(value.optionalDecisions, x => x.id, errors, 'optional decision')
+  unique(value.compatibility.packRefs, x => x.id, errors, 'pack identity')
+  const roles = new Set(value.semanticRoles.map(x => x.id))
+  for (const view of value.surfaceRoles) {
+    if (view.semanticRoleRefs.some(id => !roles.has(id))) errors.push('dangling surface semantic role')
+  }
+  // No extension handlers are registered by this additive profile. Optional
+  // opaque payloads remain inert. Required semantics cannot be silently ignored.
+  if (value.extensions.some(x => x.required)) errors.push('required extension unsupported')
+  return errors.length === 0
+}
+
+export function validateTemplateDefinition(input) {
+  return run('definition', input, (value, errors) => definition(value, errors))
+}
+
+function inventory(records, errors) {
+  const entries = new Map(), identities = new Set()
+  if (!Array.isArray(records) || records.length > 256) {
+    errors.push('invalid reference inventory'); return entries
+  }
+  for (const record of records) {
+    if (!shape('record', record, errors)) continue
+    const { ref, document } = record
+    const key = canonicalize(ref), identity = canonicalize([ref.kind, ref.id, ref.version])
+    if (identities.has(identity)) errors.push('ambiguous reference inventory')
+    identities.add(identity)
+    if (!same(ref, refFor(ref.kind, ref.id, ref.version, document))) errors.push('reference digest mismatch')
+    entries.set(key, document)
+  }
+  return entries
+}
+function resolve(ref, entries, errors) {
+  const key = canonicalize(ref)
+  if (!entries.has(key)) errors.push('dangling exact reference')
+  return entries.get(key)
+}
+function extensions(value, entries, errors) {
+  for (const entry of value.extensions) {
+    resolve(entry.schemaRef, entries, errors)
+    resolve(entry.payloadRef, entries, errors)
+  }
+}
+function binding(profile, value, entries, errors) {
+  if (!shape('binding', value, errors)) return false
+  if (!same(value.templateRef, refFor('TemplateRef', profile.id, profile.version, profile))) errors.push('template binding mismatch')
+  unique(value.roles, x => x.roleRef, errors, 'role binding')
+  const roles = new Map(profile.semanticRoles.map(x => [x.id, x]))
+  for (const entry of value.roles) {
+    const role = roles.get(entry.roleRef)
+    if (!role) errors.push('unknown semantic role')
+    if (role?.cardinality === 'one' && entry.sourceRefs.length !== 1) errors.push('plural singular role binding')
+    for (const ref of entry.sourceRefs) resolve(ref, entries, errors)
+  }
+  for (const role of profile.semanticRoles) {
+    if (role.required && !value.roles.some(x => x.roleRef === role.id)) errors.push('required semantic role unbound')
+  }
+  extensions(profile, entries, errors)
+  return errors.length === 0
+}
+
+export function validateTemplateBinding(profile, projectBinding, records = []) {
+  return run('binding', { profile, projectBinding, records }, (value, errors) => {
+    if (!definition(value.profile, errors)) return
+    binding(value.profile, value.projectBinding, inventory(value.records, errors), errors)
+  })
+}
+
+export function validateTemplateRelease(profile, projectBinding, release, records = []) {
+  return run('release', { profile, projectBinding, release, records }, (value, errors) => {
+    if (!definition(value.profile, errors) || !shape('release', value.release, errors)) return
+    const entries = inventory(value.records, errors)
+    if (!binding(value.profile, value.projectBinding, entries, errors)) return
+    const templateRef = refFor('TemplateRef', value.profile.id, value.profile.version, value.profile)
+    const bindingRef = refFor('BindingRef', value.projectBinding.id, value.projectBinding.version, value.projectBinding)
+    if (!same(value.release.templateRef, templateRef) || !same(value.release.bindingRef, bindingRef)) errors.push('release binding mismatch')
+    const carriers = new Set(), sources = new Set(value.projectBinding.roles.flatMap(x => x.sourceRefs.map(canonicalize)))
+    for (const ref of value.release.projectionRefs) {
+      const projection = resolve(ref, entries, errors)
+      if (!shape('projection', projection, errors)) continue
+      if (projection.id !== ref.id || projection.version !== ref.version) errors.push('projection identity mismatch')
+      if (!same(projection.templateRef, templateRef) || !same(projection.bindingRef, bindingRef)) errors.push('projection binding mismatch')
+      if (carriers.has(projection.carrier)) errors.push('duplicate projection carrier')
+      carriers.add(projection.carrier)
+      if (!value.profile.carriers.some(x => x.id === projection.carrier)) errors.push('undeclared projection carrier')
+      for (const source of projection.sourceRefs) {
+        if (!sources.has(canonicalize(source))) errors.push('projection source outside project binding')
+        resolve(source, entries, errors)
+      }
+      for (const item of [...projection.policyRefs, ...projection.authorityDecisionRefs, projection.payloadRef, projection.capabilityRef]) resolve(item, entries, errors)
+    }
+    for (const carrier of value.profile.carriers) {
+      if (carrier.required && !carriers.has(carrier.id)) errors.push('required carrier missing')
+    }
+  })
+}
+
+/** Host declarations are structural observations, never runtime grants. */
+export function validateTemplateHost(profile, host) {
+  return run('host', { profile, host }, (value, errors, diagnostics) => {
+    if (!definition(value.profile, errors) || !shape('host', value.host, errors)) return
+    const { profile: p, host: h } = value
+    if (!same(h.templateRef, refFor('TemplateRef', p.id, p.version, p))) errors.push('host template mismatch')
+    if (!p.carriers.some(x => x.id === h.carrier)) errors.push('undeclared host carrier')
+    if (!p.compatibility.atelierVersions.includes(h.atelierVersion)) errors.push('incompatible host version')
+    unique(h.packRefs, x => x.id, errors, 'host pack')
+    for (const pack of p.compatibility.packRefs) {
+      if (!h.packRefs.some(x => same(x, pack))) errors.push('required exact pack unavailable')
+    }
+    for (const role of p.semanticRoles) if (!h.semanticPrimitives.includes(role.primitive)) {
+      if (role.required) errors.push('unsupported semantic primitive')
+      else diagnostics.push({ kind: 'semantic-role', id: role.id, status: 'unsupported', bindingAllowed: false })
+    }
+    for (const role of p.surfaceRoles) if (!h.surfacePrimitives.includes(role.primitive)) errors.push('unsupported surface primitive')
+    if (!same(p.runtimeProfileRef, h.runtimeProfileRef)) errors.push('runtime profile missing or mismatched')
+    unique(h.optionalDecisions, x => x.id, errors, 'host decision')
+    for (const observation of h.optionalDecisions) {
+      if (!p.optionalDecisions.some(x => x.id === observation.id)) errors.push('undeclared optional decision')
+      if (observation.status === 'available' && observation.capabilityRef === null) errors.push('available decision needs exact capability reference')
+      if (observation.status === 'absent' && observation.capabilityRef !== null) errors.push('absent decision cannot claim a capability reference')
+    }
+    for (const request of p.optionalDecisions) {
+      const status = h.optionalDecisions.find(x => x.id === request.id)?.status ?? 'absent'
+      diagnostics.push({ id: request.id, status, fallback: 'deterministic-or-manual', invocationAuthorized: false })
+    }
+  })
+}
+
+/** Reuse provider-neutral decision semantics; never select or invoke a provider. */
+export function validateTemplateDecision(profile, decisionId, request, result) {
+  return run('advisory-decision', { profile, decisionId, request, result }, (value, errors) => {
+    if (!definition(value.profile, errors)) return
+    if (!value.profile.optionalDecisions.some(x => x.id === value.decisionId)) errors.push('undeclared optional decision')
+    if (value.request?.task !== value.decisionId) errors.push('decision task binding mismatch')
+    if (!validateDecisionRequest(value.request).ok) errors.push('invalid decision request')
+    else if (!validateDecisionResult(value.request, value.result).ok) errors.push('invalid decision result')
+  })
+}

package/src/trackables/domain.mjs

@@ -0,0 +1,175 @@
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { boundedLearningValue, learningDigest as digest } from '../learning/contracts.mjs'
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-trackable.v1.schema.json', import.meta.url)))
+const ajv = new Ajv({ strict: true, allErrors: true }); addFormats(ajv)
+const validators = new Map()
+export const TRACKABLE_ENGINE_REVISION = 'atelier-trackable-reference@v1'
+export function validateTrackable(value, shape = 'definition') {
+  try { boundedLearningValue(value) } catch (error) { return [error.message] }
+  if (!['definition', 'request'].includes(shape)) return ['unsupported trackable shape']
+  if (!validators.has(shape)) validators.set(shape, ajv.compile({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }))
+  const validate = validators.get(shape)
+  if (!validate(value)) return validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+  if (shape === 'definition') {
+    if ((value.profile === 'recurring-practice') !== (value.schedule !== null)) return ['/schedule: daily schedule is required only for recurring practice']
+    if (value.schedule) try { new Intl.DateTimeFormat('en', { timeZone: value.schedule.timezone }).format(0) } catch { return ['/schedule/timezone: unsupported timezone'] }
+  }
+  return []
+}
+function valid(value, shape) {
+  const errors = validateTrackable(value, shape)
+  if (errors.length) throw new Error(`invalid trackable ${shape}: ${errors.join('; ')}`)
+  return value
+}
+export function releaseTrackable(definition) {
+  valid(definition, 'definition')
+  return { definition: structuredClone(definition), digest: digest(definition), engine: TRACKABLE_ENGINE_REVISION }
+}
+export function initialTrackables(scope) {
+  if (typeof scope !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(scope)) throw new Error('exact scope identity required')
+  return { scope, revision: 0, definitions: [], instances: [], evidence: [] }
+}
+function instanceFor(state, id) {
+  const instance = state.instances.find(i => i.id === id)
+  if (!instance) throw new Error('trackable instance not found in scope')
+  return instance
+}
+function definitionFor(state, pin) {
+  const release = state.definitions.find(d => d.digest === pin)
+  if (!release || releaseTrackable(release.definition).digest !== pin) throw new Error('immutable definition missing or changed')
+  return release.definition
+}
+function adoptionAt(instance, at) {
+  const adoption = instance.adoptions.findLast(a => Date.parse(a.effectiveAt) <= Date.parse(at))
+  if (!adoption) throw new Error('no adopted definition at occurrence time')
+  return adoption
+}
+function dateAt(at, timezone) {
+  const parts = new Intl.DateTimeFormat('en', { timeZone: timezone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(new Date(at))
+  return ['year', 'month', 'day'].map(k => parts.find(p => p.type === k).value).join('-')
+}
+export function trackableOccurrence(state, instanceId, occurredAt, eventId = null) {
+  return resolveOccurrence(state, instanceId, occurredAt, eventId)
+}
+function resolveOccurrence(state, instanceId, occurredAt, eventId, resolution = null) {
+  if (!/^\d{4}-\d\d-\d\dT.*Z$/.test(occurredAt) || !Number.isFinite(Date.parse(occurredAt))) throw new Error('UTC occurrence instant required')
+  const instance = instanceFor(state, instanceId), adoption = adoptionAt(instance, occurredAt)
+  const definition = definitionFor(state, adoption.definitionDigest)
+  if (definition.profile === 'qualitative-series' && (typeof eventId !== 'string' || !eventId)) throw new Error('qualitative occurrence requires source event identity')
+  // Replay owns a journal-pinned calendar observation. New commands and previews
+  // omit it and resolve using the current host. Never accept it in command input.
+  const localDate = resolution ? resolution.occurrence?.localDate
+    : definition.schedule ? dateAt(occurredAt, definition.schedule.timezone) : null
+  if (definition.schedule) {
+    if (typeof localDate !== 'string' || !/^\d{4}-\d\d-\d\d$/.test(localDate) || !Number.isFinite(Date.parse(localDate)) || new Date(localDate).toISOString().slice(0, 10) !== localDate) throw new Error('invalid recorded calendar date')
+  } else if (localDate !== null) throw new Error('invalid recorded calendar date')
+  const key = { scope: state.scope, instanceId, definitionDigest: adoption.definitionDigest, effectiveAt: adoption.effectiveAt,
+    window: localDate ?? (definition.profile === 'milestone' ? 'milestone' : eventId) }
+  const occurrence = { id: digest(key), ...key, localDate, timezone: definition.schedule?.timezone ?? null }
+  if (resolution) {
+    const tzdata = resolution.tzdata
+    if (tzdata !== null && (typeof tzdata !== 'string' || !/^[a-zA-Z0-9._-]{1,64}$/.test(tzdata))) throw new Error('invalid recorded timezone data version')
+    if (digest(resolution) !== digest({ occurredAt, sourceRef: eventId, occurrence, tzdata })) throw new Error('recorded occurrence identity differs')
+  }
+  return occurrence
+}
+function checkResult(definition, result, value) {
+  if (definition.profile === 'qualitative-series') {
+    if (result !== 'observed' || typeof value !== 'string' || !value.trim()) throw new Error('qualitative series requires an attributed text observation')
+  } else if (result === 'observed' || (result === 'completed' ? value !== true : value !== null)) {
+    throw new Error('practice/milestone completion requires true; other dispositions carry no value')
+  }
+}
+function effectiveEvidence(state, instanceId) { return state.evidence.filter(e => e.instanceId === instanceId && !e.withdrawn) }
+// The same reducer is used by authoring preview, durable local execution and
+// host adapters. Host authentication and storage are separate responsibilities.
+export function reduceTrackables(previous, command, { actor, recordedAt, occurrenceResolution = null } = {}) {
+  valid(command, 'request')
+  if (occurrenceResolution !== null && (command.operation !== 'record' || typeof occurrenceResolution !== 'object' || Array.isArray(occurrenceResolution))) throw new Error('recorded occurrence requires a record command')
+  if (typeof actor !== 'string' || !actor || actor.length > 128 || !Number.isFinite(Date.parse(recordedAt))) throw new Error('actor and recording time required')
+  if (command.expectedRevision !== previous.revision) throw new Error('trackable revision changed; reload')
+  const state = structuredClone(previous), input = command.input
+  if (command.operation === 'release') {
+    const release = releaseTrackable(input.definition)
+    if (state.definitions.some(d => d.definition.id === input.definition.id && d.definition.revision === input.definition.revision)) throw new Error('definition revision already exists; publish a new revision')
+    state.definitions.push(release)
+  } else if (command.operation === 'instantiate') {
+    if (state.instances.some(i => i.id === input.instanceId)) throw new Error('instance identity already exists')
+    const definition = definitionFor(state, input.definitionDigest)
+    state.instances.push({ id: input.instanceId, subject: input.subject, owner: actor, lifecycle: 'active',
+      disposition: definition.profile === 'milestone' ? 'open' : null, dispositionBasis: [],
+      adoptions: [{ definitionDigest: input.definitionDigest, effectiveAt: input.effectiveAt }] })
+  } else if (command.operation === 'correct') {
+    const evidence = state.evidence.find(e => e.id === input.evidenceId)
+    if (!evidence) throw new Error('evidence not found in scope')
+    if (evidence.withdrawn) throw new Error('withdrawn evidence cannot be silently restored')
+    if (input.replacement) checkResult(definitionFor(state, evidence.occurrence.definitionDigest), input.replacement.result, input.replacement.value)
+    evidence.corrections.push({ actor, recordedAt, reason: input.reason, previous: { result: evidence.result, value: evidence.value } })
+    if (input.replacement) Object.assign(evidence, input.replacement)
+    else evidence.withdrawn = true
+  } else {
+    const instance = instanceFor(state, input.instanceId)
+    if (command.operation === 'lifecycle') {
+      if (instance.lifecycle === 'retired') throw new Error('retired instance cannot be resumed; instantiate separately')
+      instance.lifecycle = input.status
+    } else if (command.operation === 'adopt') {
+      if (instance.lifecycle === 'retired') throw new Error('retired instance cannot adopt')
+      const definition = definitionFor(state, input.definitionDigest), last = instance.adoptions.at(-1)
+      const previousDefinition = definitionFor(state, last.definitionDigest)
+      if (definition.id !== previousDefinition.id || definition.profile !== previousDefinition.profile || definition.revision <= previousDefinition.revision) throw new Error('adoption requires a later compatible definition revision')
+      if (Date.parse(input.effectiveAt) <= Date.parse(last.effectiveAt) || state.evidence.some(e => e.instanceId === instance.id && Date.parse(e.occurredAt) >= Date.parse(input.effectiveAt))) throw new Error('adoption would reinterpret recorded occurrences')
+      instance.adoptions.push({ definitionDigest: input.definitionDigest, effectiveAt: input.effectiveAt })
+    } else if (command.operation === 'record') {
+      if (instance.lifecycle !== 'active') throw new Error('recording requires active tracking')
+      const evidence = input.evidence
+      if (state.evidence.some(e => e.id === evidence.id)) throw new Error('evidence identity already exists')
+      if (Date.parse(evidence.occurredAt) > Date.parse(recordedAt)) throw new Error('future occurrence evidence refused')
+      const occurrence = resolveOccurrence(state, instance.id, evidence.occurredAt, evidence.source.ref, occurrenceResolution)
+      checkResult(definitionFor(state, occurrence.definitionDigest), evidence.result, evidence.value)
+      if (state.evidence.some(e => e.instanceId === instance.id && e.source.kind === evidence.source.kind && e.source.ref === evidence.source.ref)) throw new Error('source event already recorded; retry the original command or correct it')
+      state.evidence.push({ ...structuredClone(evidence), instanceId: instance.id, occurrence, recorder: actor, recordedAt, corrections: [], withdrawn: false })
+    } else if (command.operation === 'disposition') {
+      if (instance.disposition === null) throw new Error('domain fulfillment is available only for the milestone profile')
+      const evidence = input.basisEvidenceIds.map(id => effectiveEvidence(state, instance.id).find(e => e.id === id))
+      if (evidence.some(e => !e) || new Set(input.basisEvidenceIds).size !== evidence.length) throw new Error('fulfillment basis must identify distinct current evidence in this instance')
+      if (input.status === 'fulfilled' && !evidence.some(e => e.result === 'completed')) throw new Error('fulfillment requires current completion evidence')
+      instance.disposition = input.status; instance.dispositionBasis = [...input.basisEvidenceIds]
+    }
+  }
+  state.revision++
+  return state
+}
+export function trackableView(state, { instanceId, at = new Date().toISOString() }) {
+  const instance = instanceFor(state, instanceId), current = trackableOccurrence(state, instanceId, at, 'current')
+  const definition = definitionFor(state, current.definitionDigest)
+  const groups = new Map()
+  for (const evidence of effectiveEvidence(state, instanceId)) {
+    if (Date.parse(evidence.occurredAt) > Date.parse(at)) continue
+    if (!groups.has(evidence.occurrence.id)) groups.set(evidence.occurrence.id, { occurrence: evidence.occurrence, evidence: [] })
+    groups.get(evidence.occurrence.id).evidence.push(evidence)
+  }
+  if (definition.profile !== 'qualitative-series' && !groups.has(current.id)) groups.set(current.id, { occurrence: current, evidence: [] })
+  const occurrences = [...groups.values()].map(({ occurrence, evidence }) => {
+    const values = [...new Set(evidence.map(e => e.result))]
+    return { occurrence, result: values.length === 0 ? 'unobserved' : values.length > 1 ? 'disputed' : values[0],
+      evidenceIds: evidence.map(e => e.id), values: evidence.map(e => e.value), assistance: [...new Set(evidence.map(e => e.assistance))] }
+  })
+  const staleDisposition = instance.disposition === 'fulfilled' && !effectiveEvidence(state, instanceId).some(e => instance.dispositionBasis.includes(e.id) && e.result === 'completed')
+  return { schema: 'atelier-trackable-view@v1', engine: TRACKABLE_ENGINE_REVISION, scope: state.scope, revision: state.revision,
+    instanceId, subject: instance.subject, definitionDigest: current.definitionDigest, at, lifecycle: instance.lifecycle,
+    disposition: instance.disposition, dispositionEvidence: staleDisposition ? 'needs-reconsideration' : 'current', occurrences,
+    coverage: 'recorded-evidence-and-current-window', completedOccurrences: occurrences.filter(o => o.result === 'completed').length,
+    evidenceQuality: occurrences.some(o => o.result === 'disputed') ? 'disputed' : (!occurrences.length || occurrences.some(o => o.result === 'unobserved')) ? 'missing' : 'available',
+    attention: 'unassessed', progressPercent: null, abilityAssessed: false, interpretationLimits: definition.interpretationLimits }
+}
+export function previewTrackable({ definition, subject = 'preview-subject', at, effectiveAt = at, evidence = [] }) {
+  let state = initialTrackables('preview')
+  let serial = 0
+  const apply = (operation, input) => { state = reduceTrackables(state, { schema: 'atelier-trackable-command@v1', requestId: `preview-${++serial}`, expectedRevision: state.revision, operation, input }, { actor: 'preview-author', recordedAt: at }) }
+  apply('release', { definition }); apply('instantiate', { instanceId: 'preview', subject, definitionDigest: digest(definition), effectiveAt })
+  for (const entry of evidence) apply('record', { instanceId: 'preview', evidence: entry })
+  return { ...trackableView(state, { instanceId: 'preview', at }), mode: 'preview', persisted: false }
+}

package/src/trackables/store.mjs

@@ -0,0 +1,114 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { boundedLearningValue, learningDigest as digest } from '../learning/contracts.mjs'
+import { ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../project/private-state.mjs'
+import { withPrivateLock, publishPrivateFile, createVerifiedFileSequence, isPendingPrivateWrite } from '../project/durable-state.mjs'
+import { initialTrackables, reduceTrackables, trackableView, validateTrackable } from './domain.mjs'
+export * from './domain.mjs'
+
+// A private local reference adapter. Product hosts call the domain reducer from
+// their existing authenticated writer; they must not mirror member state here.
+export function createTrackableStore({ workspaceRoot, scope, actor }) {
+  const root = fs.realpathSync(workspaceRoot)
+  initialTrackables(scope)
+  if (typeof actor !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(actor)) throw new Error('local actor identity required')
+  const identity = { schema: 'atelier-trackable-local@v1', scope, rootDigest: digest(root) }
+  function placement() {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')))
+    try {
+      if (execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })) throw new Error('tracked')
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env, stdio: 'ignore' })
+    } catch { throw new Error('trackables require ignored, untracked .atelier-local/ in a Git workspace') }
+  }
+  function directory(...parts) {
+    return ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, '.atelier-local', 'trackables', digest(scope).slice(7), ...parts) })
+  }
+  placement()
+  const stateDir = directory(), events = directory('events'), identityPath = path.join(stateDir, 'identity.json')
+  withPrivateLock(path.join(stateDir, 'operation.lock'), () => {
+    if (!fs.existsSync(identityPath)) {
+      if (fs.readdirSync(events).some(n => !isPendingPrivateWrite(n))) throw new Error('trackable identity missing from existing history')
+      publishPrivateFile(identityPath, canonicalize(identity))
+    }
+    if (readRegularTextNoFollow(identityPath) !== canonicalize(identity)) throw new Error('trackable scope or workspace identity differs')
+  })
+  const readSequence = createVerifiedFileSequence({ directory: events, initial: () => ({ state: initialTrackables(scope), events: [], head: null, replayError: null }),
+    apply(text, history, index, name) {
+      if (name !== `${String(index).padStart(10, '0')}.json`) throw new Error('trackable history is not contiguous')
+      const event = JSON.parse(text); boundedLearningValue(event)
+      const { digest: pin, ...body } = event
+      if (pin !== digest(body) || body.previous !== history.head || body.scope !== scope || body.revision !== index || history.events.some(e => e.command.requestId === body.command.requestId)) throw new Error('trackable history integrity mismatch')
+      const legacy = body.schema === 'atelier-trackable-event@v1'
+      if (!legacy && body.schema !== 'atelier-trackable-event@v2') throw new Error('unsupported trackable event schema')
+      if (validateTrackable(body.command, 'request').length) throw new Error('invalid journal command')
+      const invalidResolution = legacy ? Object.hasOwn(body, 'occurrenceResolution')
+        : body.command.operation === 'record'
+          ? !body.occurrenceResolution || typeof body.occurrenceResolution !== 'object' || Array.isArray(body.occurrenceResolution)
+          : body.occurrenceResolution !== null
+      if (invalidResolution) throw new Error('trackable event resolution missing or unexpected')
+      let state = null, replayError = history.replayError
+      if (!replayError) {
+        state = reduceTrackables(history.state, body.command, { actor: body.actor, recordedAt: body.recordedAt, occurrenceResolution: legacy ? null : body.occurrenceResolution })
+        if (digest(state) !== body.stateDigest) {
+          if (!legacy || body.command.operation !== 'record') throw new Error('trackable replay state differs')
+          // Old events did not retain their calendar resolution. Keep the chain
+          // exportable, but never treat a differing reconstructed state as truth.
+          replayError = { code: 'legacy-replay-state-differs', revision: index, message: 'legacy trackable replay state differs; original timezone data may be required' }
+          state = null
+        }
+      }
+      return { state, events: [...history.events, event], head: pin, replayError }
+    } })
+  function read() {
+    placement(); directory(); directory('events')
+    if (readRegularTextNoFollow(identityPath) !== canonicalize(identity)) throw new Error('trackable identity changed')
+    const names = fs.readdirSync(events).filter(n => !isPendingPrivateWrite(n))
+    if (names.length > 10000) throw new Error('trackable event limit exceeded')
+    let total = 0
+    for (const name of names) {
+      const stat = fs.lstatSync(path.join(events, name)); total += stat.size
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024 || total > 32 * 1024 * 1024) throw new Error('trackable journal limit or custody violation')
+    }
+    return readSequence()
+  }
+  read()
+  function verifiedRead() {
+    const h = read()
+    if (h.replayError) throw new Error(h.replayError.message)
+    return h
+  }
+  return Object.freeze({
+    snapshot() { const h = verifiedRead(); return { ...h.state, head: h.head, authenticated: false } },
+    view(query) { return trackableView(verifiedRead().state, query) },
+    execute(command) {
+      command = boundedLearningValue(command)
+      const errors = validateTrackable(command, 'request')
+      if (errors.length) throw new Error(errors.join('; '))
+      return withPrivateLock(path.join(directory(), 'operation.lock'), () => {
+        const h = verifiedRead(), prior = h.events.find(e => e.command.requestId === command.requestId)
+        if (prior) {
+          if (digest({ command: prior.command, actor: prior.actor }) !== digest({ command, actor })) throw new Error('request identity reused with different input or actor')
+          return { duplicate: true, revision: prior.revision, eventDigest: prior.digest, currentRevision: h.state.revision, persisted: true }
+        }
+        // Leave bounded space for corrections and retirement after ordinary writes stop.
+        if (h.state.revision >= (['correct', 'lifecycle'].includes(command.operation) ? 10000 : 9000)) throw new Error('trackable capacity reached; retain/export this history')
+        const recordedAt = new Date().toISOString(), state = reduceTrackables(h.state, command, { actor, recordedAt })
+        const occurrenceResolution = command.operation === 'record' ? { occurredAt: command.input.evidence.occurredAt, sourceRef: command.input.evidence.source.ref,
+          occurrence: state.evidence.at(-1).occurrence, tzdata: process.versions.tz ?? null } : null
+        const body = { schema: 'atelier-trackable-event@v2', scope, revision: state.revision, previous: h.head, command, actor, recordedAt, occurrenceResolution, stateDigest: digest(state) }
+        const event = { ...body, digest: digest(body) }, bytes = canonicalize(event)
+        if (Buffer.byteLength(bytes) > 256 * 1024) throw new Error('trackable event limit exceeded')
+        const used = h.events.reduce((sum, e) => sum + Buffer.byteLength(canonicalize(e)), 0)
+        const limit = ['correct', 'lifecycle'].includes(command.operation) ? 32 * 1024 * 1024 : 28 * 1024 * 1024
+        if (used + Buffer.byteLength(bytes) > limit) throw new Error('trackable journal capacity reached')
+        publishPrivateFile(path.join(events, `${String(state.revision).padStart(10, '0')}.json`), bytes)
+        const actual = verifiedRead()
+        if (actual.head !== event.digest || digest(actual.state) !== body.stateDigest) throw new Error('trackable durable readback differs')
+        return { duplicate: false, revision: state.revision, eventDigest: event.digest, stateDigest: body.stateDigest, persisted: true }
+      })
+    },
+    exportHistory() { const h = read(); return { identity, events: h.events, head: h.head, private: true, authenticated: false, stateVerified: h.replayError === null, replayError: h.replayError } },
+  })
+}