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

package/docs/repo-boundary-guard.md

@@ -260,10 +260,33 @@ That is how a public site's owner-authorized mock cart stranded real work on a
 machine for weeks.
 
 - `pre-commit` runs `atelier boundary check --staged` — added lines in the
-  staged diff.
+  index Git is committing, including the temporary index of `git commit -a`
+  or `git commit <paths>` and a linked worktree's own index.
 - `pre-push` runs `atelier boundary push-check` — git writes the ref updates to
-  the hook's stdin, and only that range is judged. A brand-new branch is diffed
-  against the empty tree, so nothing slips through unscanned.
+  the hook's stdin, and only that range is judged: the change from the
+  remote's commit to the pushed tip, and every commit the push carries that the
+  remote's tracking refs do not hold, each against its parent, so content added
+  and removed again within the push is still caught (the finding names its
+  commit). A merge is judged only for what is new against all of its parents,
+  so a pull merge into the branch you push is not refused for what the remote
+  already holds; merging another branch into a feature branch can still be
+  refused through the change from the remote's commit, as before. The hook
+  passes the remote Git names: a configured remote, or a URL matched to the
+  remote configured with it. Only that remote's tracking refs, stale ones
+  included, exclude commits (a remote whose `pushurl` names another
+  repository is still scoped by its fetch-side tracking refs); a URL no remote
+  is configured with excludes only the remote's commit. A hook installed before this judges against every
+  remote's tracking refs, so reinstall it (`atelier boundary install-hooks`)
+  for history that only another remote holds to be judged on its way to a new
+  one. A brand-new branch is diffed against the empty tree, in SHA-1 and SHA-256
+  repositories alike, so nothing slips through unscanned. A push carrying more
+  than 1000 such commits, or more evidence than the aggregate budget, is
+  refused; push it in smaller parts, an earlier commit first. Each diff reads
+  what it needs, so a history that swaps large binaries back and forth makes
+  the hook slow, within the commit cap and per-diff limits. The remote's
+  tracking refs are found by name: a remote whose fetch refspec writes into
+  another remote's namespace, or two remote names that differ only in case on
+  a case-insensitive file system, can blur which history the remote holds.
 - `atelier boundary audit` scans the current working tree by default and
   **reports without blocking**, listing matches, incomplete-read diagnostics,
   and declared exceptions with their reasons. Use `--head` for a committed

package/docs/semantic-operation.md

@@ -1,9 +1,10 @@
 # Semantic operation: internal vanilla profile
 
 `src/knowledge/semantic-operation.mjs` connects a host's extraction to the
-existing intake and knowledge owners. It is an internal library. There is no
-public export, registered schema or CLI command yet. The proposed consumer is
-an agent operating the experimental Atelier CLI after Foundation registers it.
+existing intake and knowledge owners. It is an internal library with no public
+export or registered schema. Since 0.2.0-alpha.13 the experimental CLI reaches
+it as `atelier knowledge semantic OPERATION`; an agent operating that command
+is its intended consumer.
 
 Atelier never invokes a model. The host supplies its raw output, its normalized
 candidate envelope, configuration pins and usage report. A deterministic or

package/docs/upgrade.md

@@ -9,6 +9,59 @@ 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.14
+
+`atelier upgrade closure --npm-root ABSOLUTE_NPM_ROOT` plans a check of a staged
+candidate's own dependency closure before an upgrade. It reads the candidate's
+lockfile and manifests only and runs no npm command. Exit code 3 is a completed
+plan and exit code 2 a refusal; the command never exits 0, because a plan is not
+proof of an offline reinstall. It refuses `--__proto__` as an unsupported flag.
+See [Consumer dependency closure plan](#consumer-dependency-closure-plan).
+
+This release also introduces `@mnstry/atelier/ui`, a tenant-neutral control
+grammar for local Atelier tooling and compatible downstream interfaces. Existing
+consumers do not need to change. Consumers that adopt it map the
+`--system-control-*` custom properties to their own theme.
+
+No schema or stored record format changes in this release. The boundary checks
+now judge work they used to miss, so a commit or push that passed on
+0.2.0-alpha.13 can be refused, and a few other results change:
+
+- Reinstall the boundary hooks with `atelier boundary install-hooks`. The new
+  pre-push hook passes the remote Git names, so history held only by another
+  remote is judged on its way to a new one. The push check judges every commit
+  the remote's tracking refs do not hold, each against its parent, binaries
+  included. A push carrying more than 1000 such commits or more than the
+  evidence budget is refused with `content-scan-incomplete`; push it in
+  smaller parts.
+- The pre-commit check reads the index and work tree Git names, so
+  `git commit -a`, `git commit <paths>` and commits from a linked worktree are
+  judged. It blocks with `pre-commit-repo-unresolved` when no single declared
+  repository is being committed, as the push check does.
+- The content scan pins its diff format, so an external diff, a textconv
+  driver, changed prefixes or quoted paths no longer leave a change unscanned.
+  A staged or pushed deletion of a binary file no longer blocks.
+- The semantic-field review takes only an added review marker as approval; a
+  removed marker, or one in a file name, approves nothing. `atelier upgrade`
+  applies the same rule.
+- `extract-structure` refuses `parallel: true` with `NATIVE_WORKERS_UNATTESTED`.
+- Knowledge Health regenerates its rule identity for the two graph files: the
+  `check` each assessment carries names a new `version`, `sourceTree` and
+  `graphBlob`. The rule it applies is unchanged. A workshop contribution
+  started on 0.2.0-alpha.13, completed or not, cannot start Review on this
+  release (`finding changed; refresh before selecting a new draft`); start
+  Review before upgrading, or record a new contribution.
+- `runMaintenanceService` from `@mnstry/atelier/obsidian` refuses a project
+  loader that answers with a promise when no `locateProject` is given
+  (`service-loader-not-synchronous`); on 0.2.0-alpha.13 such a service
+  protected no repository. Pass a synchronous `locateProject`, which answers
+  a project naming its folder, to keep an asynchronous loader (see
+  [Obsidian](obsidian.md)).
+
+A package update supplies no interpretation approval, source-write permission,
+publication authority or runtime activation. Rehearse this exact installed
+version in a disposable workspace before client use.
+
 ## Upgrading to 0.2.0-alpha.13
 
 The public [Knowledge Health workshop](knowledge-health/devday/public-default.md)
@@ -250,7 +303,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.13
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.14
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -258,7 +311,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.13"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.14"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -337,3 +390,122 @@ For the bounded, manually confirmed single-repository workflow, see
 commands are separate from the legacy flag-based migration workflow above.
 They preserve history and honor existing commit hooks; they do not install a
 new package or activate a runtime.
+
+## Consumer dependency closure plan
+
+`atelier upgrade closure --npm-root ABSOLUTE_NPM_ROOT` plans a check of a staged
+candidate's own dependency closure. A consumer does not inherit a dependency
+publisher's npm `overrides`, so the candidate's own lockfile is what counts.
+
+The command reads these files and no others:
+
+- the candidate's `package.json` and `package-lock.json`;
+- the installed `package.json` of every lockfile copy of the selected package;
+- `package.json` in each directory above the npm root, up to the filesystem
+  root, to refuse a parent that declares workspaces. When the npm root is under
+  your home directory, that includes a `package.json` in the home directory;
+- Atelier's own `package.json`. The CLI reads it on every run for its version;
+  this plan also takes the default package name from it when `--package` is
+  not given.
+
+It does not run npm, use the network, read npm configuration or credentials, or
+write anything. The directory need not be an Atelier workspace, and `--npm-root`
+has no default.
+
+Every run prints exactly one JSON document with `"proof": "not-run"`, including
+a run whose arguments are refused. A completed plan holds:
+
+- the lockfile's SHA-256, version and entry count;
+- entries by source (`npm`, `git`, `local_path`, `link`, `bundled` and
+  `unclassified`, an installed entry with no `resolved`); the counts add up to
+  the entry count;
+- the registry hosts the lockfile names, and separately the URL schemes (`http`,
+  `https`) it uses;
+- the number of registry tarballs an offline proof would need;
+- lockfile entries whose `os`, `cpu` or `libc` excludes this host;
+- the selected package's lockfile copies, and under `manifests` the path, name,
+  version and SHA-256 of each installed manifest that was read;
+- the selected package's exact `overrides` that were checked against every
+  installed copy, the ones with no copy, and the ones left unchecked: a
+  version-selector key, a nested override, a value that is not an exact
+  version, or a package that a link provides (`link-only`, or `linked-copy`
+  when a registry copy is installed beside the link);
+- every refusal, with its code, one `reason`, a message and a next step.
+
+A refused plan holds its refusals and whatever else was established. A refusal
+of the arguments, the npm root or the shape of the lockfile stops the plan
+there, so it holds nothing about the lockfile's entries; any other refusal is
+listed beside the rest of the classification.
+
+Exit code 3 means a completed plan. Exit code 2 means a refusal: the JSON
+document, then `[code] message` with a `Next:` step on standard error. The
+command never exits 0: a plan is not a pass, and this command does not prove an
+offline reinstall.
+
+Overrides are taken from the installed manifest only when it is the package the
+lockfile records: each copy's manifest must declare the selected name and the
+version of its own lockfile entry, and all copies must be at one version with
+the same overrides. Otherwise the plan is refused and no override is reported
+as checked.
+
+Refusals reuse existing codes:
+
+- `usage`: the input is not supported. Reasons: `npm-root-required`,
+  `npm-root-not-absolute`, `npm-root-not-directory`, `npm-root-linked` (the
+  path is a link or passes through one; the refusal prints the directory's
+  `realPath` to pass instead), `argument-unsupported` (an unknown flag, an
+  extra argument, a flag with no value, an empty `--package` or
+  `--registry-host`, or a flag given more than once; an empty value after
+  `--npm-root=` is `npm-root-required`), `manifest-missing`, `lockfile-missing`,
+  `lockfile-invalid` (not a JSON object, or a `packages` entry that is not an
+  object), `lockfile-version` (version 1, or no `packages` map), `workspaces`,
+  `prefix-mismatch` (a parent directory declares workspaces) and
+  `linked-node-modules`.
+- `consumer-closure-incomplete`: an offline reinstall could not be proven for a
+  lockfile entry. Reasons: `missing-integrity`, `git-source`, `other-host`,
+  `outside-project`, `link-target-missing` (a link that names no folder),
+  `zero-copies`, `selected-package-unreadable`, `selected-package-mismatch`
+  (an installed manifest that is not the package its lockfile entry records)
+  and `selected-copies-differ`.
+- `override-not-inherited`: reason `copy-off-pin`. A copy is installed at a
+  version other than the selected package's exact pin. More than one copy, all
+  at the pin, is reported and not refused.
+
+Options:
+
+- `--package NAME` selects the package whose overrides are checked. It defaults
+  to `@mnstry/atelier`.
+- `--registry-host HOST[,HOST]` names the approved registry hosts. A tarball on
+  any other host, or at a URL with no readable host, is then refused. Without
+  it, hosts are reported and `approvedRegistryVerified` is `false`, because the
+  plan does not read npm configuration.
+
+Give each option once, with a value, after the word `closure`. An option with
+an empty value is refused; leave the option out to use its default.
+
+Limits:
+
+- The plan cannot run `npm prefix`, so `prefixVerified` is always `false`.
+  Instead it requires `--npm-root` to be the directory's real path and refuses
+  any parent directory of it that declares workspaces, whether or not that
+  parent's workspaces include the candidate. A path that is a link, or passes
+  through one, is refused, with its `realPath` in the JSON result. On macOS,
+  `/tmp` is a link into `/private` and `$TMPDIR` passes through `/var`, another
+  such link, so a candidate staged there needs its real path (for example
+  `pwd -P` from inside it).
+- Containment of links and local files is checked by path, without following
+  links. The folder a link points to is not opened: an override for a package
+  that a link provides is listed as unchecked, never as checked.
+- Approving a host does not verify the transport. A host is matched by its
+  exact name and port, whatever the scheme; `registrySchemes` counts `http`
+  and `https` separately.
+- The manifest binding compares the name and version the installed manifest
+  declares. It does not verify the installed files against the lockfile's
+  `integrity`.
+- Platform evidence uses this process's `os` and `cpu`; `libc` is unknown
+  unless a caller of `planConsumerClosure` supplies it.
+- A flag with no value placed before the word `closure` (for example
+  `atelier upgrade --package closure`) takes `closure` as its value, so the
+  ordinary upgrade command runs instead of this one.
+- `lockTreeDifferences`, the comparison of two `npm ls` trees, is in the source
+  but is not exported from the package and no command uses it.

package/fixtures/templates/local-library.v1.json

@@ -67,7 +67,8 @@
       "0.2.0-alpha.9",
       "0.2.0-alpha.10",
       "0.2.0-alpha.12",
-      "0.2.0-alpha.13"
+      "0.2.0-alpha.13",
+      "0.2.0-alpha.14"
     ],
     "packRefs": []
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.13",
+  "version": "0.2.0-alpha.14",
   "private": false,
   "description": "Local toolkit that turns a Git repository into an ontology-governed knowledge graph, enforcement layer, and runtime for people, agents, and tools. No telemetry or required hosted account; optional host-bound vault adapters.",
   "keywords": [
@@ -61,6 +61,7 @@
     "./readiness": "./src/readiness/readiness.mjs",
     "./readiness-protocols": "./src/readiness-protocols/bundled-pack.mjs",
     "./server": "./src/server/local-sidecar.mjs",
+    "./ui": "./src/ui/control-system.mjs",
     "./harness": "./src/harness/context.mjs",
     "./collaboration": "./src/collaboration/index.mjs",
     "./support": "./src/support/support-bundle.mjs",

package/plugins/obsidian/main.js

@@ -196,11 +196,14 @@ class AtelierStatusModal extends obsidian.Modal {
 class AtelierProjectionPlugin extends obsidian.Plugin {
   async onload() {
     this.channel = null
+    this.lastObservedStatus = null
     this.session = null
     this.cycling = null
     this.unloaded = false
+    this.channelAdmitted = false
     this.view = { state: 'connecting', reason: 'not-yet-asked', report: null }
     this.shownState = null
+    this.noticeState = null
     // A round's failure that differs from the failure shown, not yet seen twice in a row.
     this.pendingFailure = null
     this.appVersion = typeof obsidian.apiVersion === 'string' ? obsidian.apiVersion : null
@@ -226,6 +229,7 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
       this.setView({ state: 'not-set-up', reason: 'node-modules-unavailable', report: null })
       return
     }
+    this.channelAdmitted = true
     // This launch of the plugin: the service tells two apps holding the same vault apart by it.
     this.instanceId = `pi-${this.crypto.randomBytes(16).toString('hex')}`
     await this.readChannel()
@@ -238,6 +242,8 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
     // The lease lapses by itself; releasing it says at once that the vault closed. A round still under way stops at its
     // next step, and a session it opens after this is released at once.
     this.unloaded = true
+    this.channelAdmitted = false
+    this.lastObservedStatus = null
     const session = this.session
     this.session = null
     if (this.channel && session) void this.release(this.channel, session)
@@ -245,6 +251,7 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
 
   // Obsidian calls this when data.json changed on disk: Atelier republished the channel.
   async onExternalSettingsChange() {
+    if (!this.channelAdmitted || this.unloaded) return
     await this.readChannel()
     // A round under way still speaks for the old channel; the next one uses the new.
     if (this.cycling) await this.cycling
@@ -252,13 +259,19 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
   }
 
   async readChannel() {
+    if (!this.channelAdmitted || this.unloaded) return
     let data = null
     try { data = await this.loadData() } catch { data = null }
+    if (!this.channelAdmitted || this.unloaded) return
     const next = channelOf(data)
     const same = next && this.channel && next.host === this.channel.host && next.port === this.channel.port && next.scopeId === this.channel.scopeId && next.bearer === this.channel.bearer
-    if (!same) this.session = null
+    if (!same) {
+      this.session = null
+      this.lastObservedStatus = null
+    } else if (this.lastObservedStatus?.channel === this.channel) this.lastObservedStatus.channel = next
     this.channel = next
     if (next === null) this.setView({ state: 'not-set-up', reason: data === null ? 'no-channel-data' : 'channel-data-unusable', report: null })
+    else if (!same) this.setView({ state: 'connecting', reason: 'not-yet-asked', report: null })
   }
 
   // One round: shake hands (once per session), renew the lease, read the status.
@@ -270,12 +283,12 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
 
   // Whether a round that started for `channel` may still act.
   current(channel) {
-    return !this.unloaded && channel === this.channel
+    return this.channelAdmitted && !this.unloaded && channel === this.channel
   }
 
   async runCycle() {
     const channel = this.channel
-    if (channel === null || this.unloaded) return
+    if (!this.channelAdmitted || channel === null || this.unloaded) return
     if (this.session === null) {
       if (!(await this.handshake(channel))) return
     } else {
@@ -290,6 +303,7 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
           return
         }
         // The service started again since, the vault's key changed, or the session is not accepted: shake hands at once.
+        this.lastObservedStatus = null
         if (!(await this.handshake(channel))) return
       }
     }
@@ -386,13 +400,18 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
 
   unreachable(answer) {
     const reason = answer.kind === 'unreachable' ? answer.code : typeof answer.error === 'string' ? answer.error : answer.body && typeof answer.body.error === 'string' ? answer.body.error : `answered-${answer.statusCode}`
-    return { state: 'unreachable', reason, report: null }
+    // Retain history only for a transport interruption, never an unsealed or
+    // refused answer, failed listener proof or unknown authentication state.
+    const transportFailure = answer.kind === 'unreachable' && ['refused', 'timeout'].includes(answer.code)
+    return { state: 'unreachable', reason, report: null, transportFailure }
   }
 
   // What a round found. A failure other than the one shown ('not set up' where 'service unreachable' is shown, or the other
   // way round) is shown only when the next round finds it too, so answers that alternate between them do not make the
   // status bar flip. Anything else is shown at once.
   showRound(view) {
+    // A setup refusal clears remembered evidence even while its label is debounced.
+    if (view.state === 'not-set-up' || (view.state === 'unreachable' && view.transportFailure !== true)) this.lastObservedStatus = null
     if (ROUND_FAILURES.has(view.state) && ROUND_FAILURES.has(this.shownState) && view.state !== this.shownState && this.pendingFailure !== view.state) {
       this.pendingFailure = view.state
       return
@@ -404,11 +423,32 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
     // Nothing is shown once the plugin unloaded.
     if (this.unloaded) return
     this.pendingFailure = null
-    const previous = this.shownState
+    const previous = this.noticeState
+    // A transient display projection, never a freshness or permission record.
+    // Only a report of this exact channel may be remembered. `channel` is an
+    // in-memory identity binding, never shown or stored; the other fields hold
+    // no service health, edit counts, source content or credentials.
+    if (!this.channel || view.state === 'not-set-up' || view.state === 'unsupported' || (view.state === 'unreachable' && view.transportFailure !== true)) this.lastObservedStatus = null
+    else if (view.report !== null) {
+      const report = view.report
+      const observed = isPlainObject(report) && report.schema === CHANNEL.statusSchema && report.scopeId === this.channel.scopeId && isPlainObject(report.view) && report.view.state !== 'disabled' ? report.view : null
+      this.lastObservedStatus = observed === null ? null : {
+        channel: this.channel, state: view.state, reason: view.reason,
+        generationId: typeof observed.generationId === 'string' ? observed.generationId : null,
+        checkedAt: typeof observed.checkedAt === 'string' ? observed.checkedAt : null,
+      }
+    }
     this.view = view
     this.statusBarEl.setText(labelOf(view))
     this.statusBarEl.setAttr('aria-label', `${labelOf(view)} (${readable(view.reason)})`)
     this.shownState = view.state
+    // A republished channel resets the display before its first answer, but
+    // does not repeat attention notices or erase the recovery transition.
+    if (view.state === 'connecting') {
+      if (previous === null) this.noticeState = view.state
+      return
+    }
+    this.noticeState = view.state
     if (previous === view.state || previous === null) return
     if (Object.prototype.hasOwnProperty.call(ATTENTION, view.state)) new obsidian.Notice(ATTENTION[view.state](view))
     else if (view.state === 'current' && Object.prototype.hasOwnProperty.call(ATTENTION, previous)) new obsidian.Notice('Atelier: this view is current again.')
@@ -419,13 +459,22 @@ class AtelierProjectionPlugin extends obsidian.Plugin {
     const view = isPlainObject(report.view) ? report.view : {}
     const count = (value) => (Number.isInteger(value) ? String(value) : 'unknown')
     const channel = this.channel
+    const last = this.lastObservedStatus?.channel === channel ? this.lastObservedStatus : null
+    const missingGeneration = this.view.state === 'unreachable' ? 'unknown' : 'none yet'
+    const missingCheck = this.view.state === 'unreachable' ? 'unknown' : 'not yet'
     return [
       ['View', channel ? channel.scopeId : 'not set up'],
       ['State', labelOf(this.view).replace(/^Atelier: /, '')],
       ['Reason', readable(this.view.reason)],
-      ['Generation', typeof view.generationId === 'string' ? view.generationId : 'none yet'],
-      ['Prepared generation', typeof view.preparedGenerationId === 'string' ? view.preparedGenerationId : 'none yet'],
-      ['Checked at', typeof view.checkedAt === 'string' ? view.checkedAt : 'not yet'],
+      ...(this.view.state !== 'unreachable' ? [] : last ? [
+        ['Last observed state', readable(last.state)],
+        ['Last observed reason', readable(last.reason)],
+        ['Last observed generation', last.generationId || 'none yet'],
+        ['Last observed check', last.checkedAt || 'not yet'],
+      ] : [['Last observed status', 'not available']]),
+      ['Generation', typeof view.generationId === 'string' ? view.generationId : missingGeneration],
+      ['Prepared generation', typeof view.preparedGenerationId === 'string' ? view.preparedGenerationId : missingGeneration],
+      ['Checked at', typeof view.checkedAt === 'string' ? view.checkedAt : missingCheck],
       ['Held edits', count(view.heldNoteCount)],
       ['Retained edits', count(view.retainedEdits)],
       ['Pending edits', count(isPlainObject(report.pendingEdits) ? report.pendingEdits.open : null)],

package/plugins/obsidian/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "atelier-projection",
   "name": "Atelier",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "minAppVersion": "1.13.7",
   "description": "Shows whether this Atelier view is current and tells Atelier's maintenance service that the vault is open. Shipped by Atelier into the vaults it manages.",
   "author": "MNSTRY",