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

package/docs/template-profile.md

@@ -0,0 +1,164 @@
+# Portable template profiles
+
+Status: Next-release package API. Import validators from
+`@mnstry/atelier/templates` and canonical project binding from
+`@mnstry/atelier/template-bindings`. The versioned schema is exported at
+`@mnstry/atelier/contracts/atelier-template-profile.v1.schema.json`.
+These APIs do not establish installed product-host acceptance.
+
+A template profile names semantic roles, surface roles, supported carriers,
+compatibility and limits. An adopter binds those roles to its own source. The
+profile carries no project content, renderer, runtime handler or permission.
+
+## Four independent grammars
+
+- Semantic roles describe resource, relation, facet, asset, collection, sequence,
+  occurrence, offer and action-descriptor structure. Profiles choose a subset.
+- Surface roles describe composition: Shell, region, collection, card, detail,
+  graph, filter, offer, status, refusal and receipt views. They reference semantic
+  role identifiers, not executable components.
+- Runtime meaning is an optional opaque `RuntimeProfileRef`. A host must supply
+  the exact profile for runtime participation; ordinary local authoring needs
+  no runtime connection. The profile never creates an operation or receipt.
+- Governance and release identities are typed digest-bound references. A
+  `TemplateRef` is not interchangeable with a source, policy, authority decision,
+  project binding, projection or release reference.
+
+## Validation stages
+
+| Entry point | Checks | Does not prove |
+| --- | --- | --- |
+| `validateTemplateDefinition(profile)` | Closed grammar, bounded data, unique roles, surface references and supported extension behavior | Adoption, content or host availability |
+| `validateTemplateBinding(profile, binding, records)` | Exact template, role cardinality, required roles, resolved source digests | Source ownership or content truth |
+| `validateTemplateRelease(profile, binding, release, records)` | Exact binding, projection/source/policy/decision/payload references, required carriers | Publication acceptance, rights or distribution |
+| `validateTemplateHost(profile, host)` | Exact version/pack/runtime requirements, primitives and optional decision observations | Host authentication, actual renderer behavior or operation permission |
+
+Every result includes `authority: structural-only`, `executionAuthority: false`
+and `publicationAuthority: false`. No result authorizes a write, network request,
+installation or publication. The implementation does not mutate inputs.
+
+Reference inventories contain `{ ref, document }` entries. All entries are
+bounded plain JSON; duplicate `(kind, id, version)` identities refuse even if
+their digests differ. References must resolve to exact supplied bytes. No URL
+fetching, path loading, provider call or dynamic extension code occurs.
+
+`templateReference(kind, id, version, document)` hashes the existing Atelier
+canonical JSON serialization of:
+
+```json
+{ "schema": "atelier-template-digest@v1", "kind": "SourceRef", "id": "sample", "version": "v1", "document": {} }
+```
+
+The digest is `sha256:` plus lowercase hexadecimal. Kind, identifier and version
+belong to the digest domain. Template, binding and release versions use SemVer;
+other source-owned versions remain opaque strings. Pack versions retain their
+existing `vN` contract. None of these digests is a signature or an authenticated
+authority decision. This new domain does not reinterpret older artifact digests.
+
+## Extensions and evolution
+
+This is a separate versioned artifact; the closed extension-pack v1 schema is
+unchanged. Profiles may link optional namespaced schema/payload references.
+Their bytes must resolve at binding/release validation, but their meanings stay
+opaque and inert. This version registers no required extension handlers and
+refuses every required extension. Do not place required behavior in optional
+annotations to evade admission.
+
+Exact compatible Atelier versions and pack digests are explicit. There is no
+automatic version coercion, range admission, migration or upgrade apply in this
+module. A new contract version and the existing owner-controlled upgrade path
+must govern changes. Keep prior source and profile artifacts for recovery.
+
+The schema follows the contract epoch's optional `contractVersion` and `ext`
+conventions. Its `ext` containers are reserved and permit no properties in this
+revision. Optional extension data must use the explicit digest-bound namespaced
+`extensions` list; required behavior cannot be smuggled through an ignored bag.
+
+## Optional advisory decisions
+
+`optionalDecisions` declares named tasks using `atelier-decision-request@v1`.
+Each is explicitly optional; the schema refuses a required provider and provides
+no vendor selector. `validateTemplateDecision` consumes the existing request and
+result validators, checks the task binding, and retains proposal-only semantics.
+It does not decide whether the answer is true or should influence the graph.
+
+A host may report `absent`, `disabled`, `unqualified` or `available`. Available
+requires an exact `CapabilityRef`; it remains an untrusted structural observation
+until the host's existing capability and authority checks qualify it. Absence
+leaves local reading and authoring usable. Every diagnostic retains a
+deterministic/manual fallback and `invocationAuthorized: false`.
+
+No decision SDK, credential, network access, provider selection or automatic
+substitution is required. Actual consent, disclosure, execution, budgets,
+revocation and qualification remain with the existing host/capability owners.
+This module adds neither a capability registry nor a second decision ontology.
+
+## Synthetic proof and remaining integration
+
+```sh
+node --test test/template-profile.test.mjs
+```
+
+The invented reading-shelf fixture exercises structural positive cases and
+refusals. It is not a real publication, owner approval, visual baseline or
+conformance certificate. Software/definition licensing never supplies content
+rights or paid-service entitlement.
+
+## Canonical project binding
+
+`@mnstry/atelier/template-bindings` exports `createTemplateProjectView(project,
+requestJson)`. Supply an existing loaded Atelier project and bounded JSON text
+with `profile`, `projectRef`, `roleNodeIds`, `target` and optional `theme`.
+For example, `roleNodeIds: { items: ['library:paper', 'library:thread'] }` binds
+the synthetic shelf's role to existing source identities. The adapter calls the
+canonical graph builder with its fresh file cache; each SourceRef binds the
+exact Markdown byte digest used by that census, not metadata alone.
+
+The initial adapter supports classified active Markdown sources bound as
+Resource, with CollectionView/StatusView presentation. CollectionView is a view
+of selected resources, not proof of a semantic Collection. An unused optional
+Collection role reports unsupported without closing local Resource authoring;
+binding it or requiring it refuses until an explicit canonical mapping exists.
+Unknown targets,
+missing or withheld selected sources, audience/repository-boundary widening,
+unsupported views, missing required roles and runtime-profile requirements
+refuse. Draft/archived sources do not appear. Local archival is not a governed
+withdrawal receipt, and old exported copies are not remotely erased.
+
+Presentation models, escaping, themes and static HTML come from the existing
+presentation package. Web and document preview are the same read-only bytes;
+no inert control pretends to be an implemented action. The adapter writes no
+source, projection, lock or release and performs no provider call. Optional
+decisions report absent with the deterministic/manual fallback.
+
+`textPreview` provides the same selected titles, summaries, self-description
+and status as plain text without CSS, script or media. It is a local low-bandwidth
+preview, not an email/chat adapter, portable document package or publication.
+
+```sh
+node --test test/template-profile.test.mjs test/template-journey.test.mjs
+```
+
+The journey test uses disposable synthetic repositories, the actual local
+maintenance engine and production `createSourceApply`, not an alternate source
+writer. A simulated person's edit is held, applied to canonical source,
+rebuilt and rendered; the old binding refuses against the new source, duplicate
+apply is idempotent and an unrelated resource remains byte-identical. The test
+does not open the desktop application, accept a release or prove accessibility
+with assistive technology. On platforms without production atomic exchange,
+the apply journey explicitly skips and must not count as platform acceptance.
+
+`npm run consumer:smoke` installs the exact tarball offline and exercises the
+template APIs by package name. Its synthetic journey binds canonical source,
+checks provider absence and audience refusal, applies an edit through the
+installed source-apply owner, rejects the stale binding, and checks idempotence
+and preservation of an unrelated source. Atomic exchange is required for the
+write portion; other platforms retain the read-only checks.
+
+The built-in [template adoption participant](template-upgrades.md) connects local
+profile adoption, exact locks, retained history and read-only projections to the
+existing upgrade transaction engine. External packs, runtime extensions and
+automatic restoration remain unsupported.
+
+Remaining integration includes interactive host wiring, all-carrier conformance,
+actual host/accessibility/visual proof, and receiving-owner acceptance.

package/docs/template-upgrades.md

@@ -0,0 +1,114 @@
+# Local template adoption
+
+The built-in `local-template-profile@1` participant prepares an inert template
+profile, graph selection and read-only projection in the existing exact-plan
+upgrade engine. It uses the same exclusive writer, exact preimages, saved bytes,
+append-only private journal, backups, commit hooks and commit verification.
+It is not a plugin registry or a second transaction engine.
+
+## Prepare and inspect
+
+Use an isolated linked worktree with one managed root repository. Commit the
+profile and selection JSON inputs before preparing. Both paths must be literal,
+distinct, root-relative regular non-executable files outside managed output.
+The selection has exactly `projectRef`, `roleNodeIds`, `target`, and optional
+`theme`. Source selection and disclosure are enforced by the existing canonical
+graph, projection policy and template composition adapter.
+
+Explicit enrollment uses `atelier.adoption-policy.json`:
+
+```json
+{
+  "schema": "mnstry.atelier-adoption-policy@v2",
+  "enabled": true,
+  "participant": "local-template-profile@1",
+  "mode": "manual-exact-plan",
+  "maxAgeSeconds": 86400,
+  "recoveryCoverage": "local-only",
+  "allowedEffects": ["template-adoption", "lock-and-projections", "git-commit"]
+}
+```
+
+The API is exported through the existing `@mnstry/atelier/upgrade` subpath:
+
+```js
+import { prepareTemplateUpgrade, explainSavedUpgrade, applySavedUpgrade }
+  from '@mnstry/atelier/upgrade'
+
+const prepared = prepareTemplateUpgrade({
+  project,
+  profileFile: 'next-profile.json',
+  selectionFile: 'next-selection.json',
+})
+const explanation = explainSavedUpgrade({ project, planFile: prepared.savedPlan })
+// Inspect the exact changes and obtain the owner's selection before applying.
+// A digest identifies bytes; it does not authenticate a human decision.
+const result = applySavedUpgrade({
+  project,
+  planFile: prepared.savedPlan,
+  confirm: prepared.plan.digest,
+})
+```
+
+There is no new CLI command family. The existing saved-plan apply, explain,
+status and recovery entry points understand the new v3 plan. Existing v2 plans
+remain supported and still refuse execution when their pinned executor changes.
+Policies are never silently converted.
+
+## Installed state
+
+The engine owns only these template paths:
+
+- `atelier-template/profile.json` and `selection.json`: Exact inert input bytes.
+- `atelier-template/adoption.json`: Validated installed state with typed refs,
+  raw input digests and the four managed-content digests/modes.
+- `atelier-template/history/<digest>.json`: Exact immutable prior adoption
+  manifest on subsequent adoption.
+- `atelier-output/template.html` and `template-binding.json`: Read-only
+  rendering and its validated source binding.
+
+The existing lock and normal four graph/projection/readiness files are refreshed
+through their original builders. The v1 lock keeps unrelated fields, provenance,
+migration history, historical success metadata, and the complete workspace
+template lineage in `lock.template`. Only package and generated information
+are refreshed. The separate adoption document owns the profile's typed identity,
+version, and digest. A profile adoption never replaces the workspace template
+identity or version. The adoption document does not hash itself recursively.
+
+First adoption refuses orphan reserved state. Later adoption verifies every
+managed preimage and the complete prior-manifest chain. Committed local changes
+to managed files refuse rather than being overwritten. Source documents and
+ordinary local configuration are never template write targets.
+
+Repeating the same valid inputs is another explicit adoption, not an implicit
+no-op: it appends a new adoption manifest linked to the previous one. Identical
+profile, selection and projection bytes are not rewritten. Existing history is
+verified and retained. Empty reserved root/history directories are harmless;
+unknown reserved child directories are refused, including empty ones.
+
+Before mutation the engine recomputes the template output using current canonical
+source and compares it to the saved bytes. After writes it verifies the installed
+profile, selection, binding and rendering against that same source. A partial or
+failed operation never reports completed adoption.
+
+## Limits and recovery
+
+External packs, runtime profiles, extension handlers, local overlays, custom
+callbacks, package installation, network retrieval, source migrations and
+automatic consent remain unsupported. This first participant does not claim
+full template migration or all-carrier conformance.
+
+The exact-plan POSIX, clean-worktree, path, Git, hook, expiry, bounded-inventory
+and local-evidence controls still apply. Only regular create/update writes are
+supported; no deletion, rename, executable mode change or arbitrary scaffolding
+is added. An accepted attempt consumes its plan, including an interrupted attempt.
+
+Use the existing operation status and recovery dry-run API. Recovery describes
+verified backups and conflicts; it never restores files, resets history, clears
+a lease, resumes a consumed plan or supplies new consent automatically. A later
+restoration needs a separately reviewed operation. Corrupted or missing evidence
+cannot become success.
+
+A completed transaction means a local candidate commit only. Independent review,
+CI, merge, publisher authentication, package release, recipient adoption,
+runtime activation and human acceptance remain separate.

package/docs/trackables.md

@@ -0,0 +1,111 @@
+# Trackables: one definition, one domain writer
+
+A Trackable follows an identifiable subject or pursuit over time. Its adopted
+definition, instance, occurrences, evidence and qualified views retain separate
+meanings. Following a practice, completing a milestone and recording a reflection
+use different profiles. A recorded result does not establish independent ability.
+
+The portable `@mnstry/atelier/trackables` API exports one domain reducer used by
+`previewTrackable` and the private `createTrackableStore` reference adapter.
+Product hosts adapt this reducer through their existing authenticated domain
+writer. They must not copy member state into a Witness-specific store.
+
+## Supported reference profile
+
+| Profile | Occurrence | Evidence | Domain fulfillment |
+| --- | --- | --- | --- |
+| Recurring practice | Local calendar day in an explicit IANA timezone | Completed, partial, skipped, waived, not applicable | Separate from completing an occurrence |
+| Milestone | One opportunity for the adopted definition | Same explicit result states | Explicit open, fulfilled or released disposition |
+| Qualitative series | Unscheduled source event | Attributed text observation | Unscored |
+
+Missing evidence is `unobserved`, never zero or automatic failure. Several
+matching reports of one occurrence count once; conflicting reports remain
+`disputed`. Manual and session records retain separate source identities and
+assistance. A source event cannot be recaptured under another evidence ID for the
+same instance. Different instances and days remain distinct.
+
+This bounded profile supports daily calendars, not arbitrary recurrence,
+quantitative meters, streaks or a universal progress score. It uses the host's
+installed IANA timezone data for new records, previews and current windows.
+Journal replay preserves each recorded occurrence's original local day. Native
+schedulers retain calendar ownership and
+must qualify their mappings, including timezone database version where needed.
+
+`releaseTrackable` validates and hashes a definition. Releasing new bytes does
+not change existing instances. `adopt` requires a later compatible revision and
+an explicit effective instant; it refuses changes that reinterpret recorded
+occurrences. Late reports resolve the definition applicable at occurrence time.
+DST changes preserve local-day identity. A timezone change uses a new definition.
+
+The immutable journal records every command, actor assertion, recording time,
+source time and resulting state digest. New events use `atelier-trackable-event@v2`;
+record events also pin the resolved occurrence, source instant/reference and host
+timezone-data version (`null` if unavailable). Replay checks these against the
+adopted definition, scope, instance and command, without recalculating the stored
+local day. Event-chain and resulting-state digest checks still apply. This is
+local integrity checking, not authentication of the host calendar or recorder.
+Corrections preserve original events and
+invalidate dependent fulfillment evidence. Lifecycle, domain fulfillment,
+evidence quality and attention remain independent. Pausing prevents new capture;
+retirement is terminal. Views describe current corrected knowledge about the
+selected occurrence time, not historical knowledge as it was then understood.
+
+## Local use and ownership
+
+Run `atelier trackable preview|release|execute|snapshot|view|export` with JSON stdin.
+The existing workspace must ignore `.atelier-local/`. Local identity is asserted,
+not authenticated. `scope` selects a private store; operating-system access is
+its trust boundary, so this is not multi-tenant access control. Exports are
+private and require deliberate handling. Withdrawal and correction retain
+history; this adapter does not claim secure erasure or automated retention.
+
+A command has `schema: "atelier-trackable-command@v1"`, `requestId`,
+`expectedRevision`, `operation` and `input`. Operations are `release`,
+`instantiate`, `adopt`, `record`, `correct`, `lifecycle` and `disposition`.
+The exported [schema](../contracts/atelier-trackable.v1.schema.json) and
+[fixtures](../fixtures/atelier-trackable) specify exact fields.
+
+`execute` locks the selected scope, verifies history, applies the shared reducer,
+atomically publishes one event and reads it back. Replaying the same request and
+actor returns the original receipt; changed input under that identity refuses.
+A lost response can therefore be reconciled by retrying the original command.
+Dead process locks use the existing private-state custody mechanism. Journal
+capacity reserves room for correction and retirement; full histories remain
+available for explicit export. No automatic archive or compaction is performed.
+
+Older `atelier-trackable-event@v1` events remain readable and can precede new v2
+events without rewriting history. They lack the original calendar observation,
+so replay still needs compatible timezone data. If replay of a legacy record
+produces a different state digest, snapshot, view and execute refuse.
+`exportHistory()` remains available after verifying the full event chain and
+returns `stateVerified: false` plus `replayError`; these raw events are not a
+verified reconstructed state. Restore the original calendar environment before
+resuming that store. Do not infer a timezone change from this diagnostic alone,
+or rewrite old digests to make them pass. Other replay and integrity failures
+still refuse; a valid reconstruction exports `stateVerified: true`.
+
+## Authoring and host adoption
+
+Definition fields `profile` and `schedule` are enforced by the reducer and
+occurrence resolver. `id` and `revision` pin meaning; `purpose` is rationale;
+`interpretationLimits` are surfaced guidance. The engine revision appears in
+release and view outputs. Host binding must additionally name immutable source
+resolution, authentication, operation authorization, evidence-source validation,
+storage and rendering. Caller-supplied source digests are provenance assertions,
+not proof that a session or instrument reported them.
+
+The reducer's optional `occurrenceResolution` context is for replay of a
+previously verified journal, never user-authored command input. Native writers
+that use it must persist and verify the command, complete resolution and state
+digest together. The local adapter derives it from the new state and never
+accepts a caller override. Existing recorded evidence keeps its occurrence when
+current rules change; new evidence and the current-window view can consequently
+resolve the same instant to a different day. The API does not silently merge or
+reinterpret those occurrences.
+
+Reference tests exercise preview/runtime parity, durable reload, scoped stores,
+correction, duplicate transport/source events, same-day instances, late evidence,
+DST, timezone adoption, simulated timezone-data drift, legacy export-only
+recovery and refusal of inconsistent replay metadata. These establish the portable subset. Authenticated
+member-host adoption, actual UI refresh and broader calendar profiles require
+separate receiving-host evidence.

package/docs/upgrade.md

@@ -9,6 +9,51 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.13
+
+The public [Knowledge Health workshop](knowledge-health/devday/public-default.md)
+uses an invented local workspace. Participants can retain their original words,
+a separate interpretation and a `note`, `perspective-only`, `disagreement` or
+`pause` response. Review is a separate optional session. A selected draft can
+produce one retained copy-only source-owner proposal; retries and reopen read
+back its original receipt instead of appending another proposal. A source owner
+reviews the proposal and edits the declaration with normal repository tools,
+then reads it back and reassesses. The browser host grants no source-apply route.
+
+`atelier knowledge semantic` exposes the existing semantic runner's eleven
+operations through JSON stdin. It retains the runner's refusal codes and saved
+failure details. The [semantic operation contract](semantic-operation.md)
+remains authoritative; this release adds no schema or package export.
+
+Existing source and local history remain owned by their original repositories.
+A package update supplies no interpretation approval, source-write permission,
+Obsidian host qualification, publication authority or runtime activation. Rehearse
+this exact installed version in a disposable workspace before client use.
+
+## Unreleased
+
+The bundled readiness pack retains its original v1 content and digest. Existing
+locks, including the prior alpha.10 release fixture, can prepare and apply both
+ordinary v2 and template v3 exact plans without first rewriting the lock.
+Discovery Harness is the architecture name; the persisted readiness entry still
+uses Discovery Engine. Actual external pack changes still require their own
+adoption procedure and are not accepted by either participant.
+
+The next release adds the responsibility workflows, source-current ingestion,
+Trackables, governed instruction adoption and local template profiles. Template
+adoption uses the existing exact-plan transaction engine with explicit v2 policy
+and v3 plans; existing policies are never converted automatically. See
+[template profiles](template-profile.md) and [template adoption](template-upgrades.md).
+Optional advisory decisions require no provider installation or activation.
+
+New Trackable journals retain resolved calendar occurrences and byte-bound state.
+Legacy v1 journals remain available as chain-verified exports when state replay
+cannot be established. Preserve historical records and use the documented
+[Trackables](trackables.md) host limits before adopting a new profile.
+Regenerate local graph/projection artifacts through the ordinary upgrade process
+and qualify each consuming host independently. A package update supplies no
+publication permission or runtime activation.
+
 ## Upgrading to 0.2.0-alpha.12
 
 This release makes the first open of an Obsidian view automatic and ships
@@ -205,7 +250,7 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -213,7 +258,7 @@ For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.13"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 

package/fixtures/atelier-architecture/binding/invalid/document.json

@@ -0,0 +1,19 @@
+{
+  "schema": "atelier-behavior-binding@v1",
+  "definition": {
+    "ref": "definitions/weekly-note.json",
+    "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "fields": [
+    {
+      "pointer": "/question",
+      "classification": "implicit",
+      "required": true,
+      "consumer": {
+        "id": "reference-note",
+        "profile": "note-v1",
+        "revision": "1"
+      }
+    }
+  ]
+}

package/fixtures/atelier-architecture/binding/valid/document.json

@@ -0,0 +1,19 @@
+{
+  "schema": "atelier-behavior-binding@v1",
+  "definition": {
+    "ref": "definitions/weekly-note.json",
+    "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "fields": [
+    {
+      "pointer": "/question",
+      "classification": "guidance",
+      "required": true,
+      "consumer": {
+        "id": "reference-note",
+        "profile": "note-v1",
+        "revision": "1"
+      }
+    }
+  ]
+}