@aikdna/kdna-studio-cli 0.10.2 → 0.13.0-rc.components.2

package/docs/CREATION_COMMAND_CONTRACT.md

@@ -0,0 +1,30 @@
+# Current command boundary
+
+Supported commands: `help`, `--help`, `--version`, `session`, `verify`, `read`. Unknown commands, repeated or unknown options fail before opening materials or output. Package exports expose metadata only; the supported executable is the bin. No deep path, alternate checkout, model, remote server or runtime fallback is selected.
+
+`session --out NEW_DIRECTORY` accepts repeated `--text FILE` and `--interview FILE`, `--synthetic-fixture`, and exactly one adoption mode. Human mode uses a controlling terminal or `--human-fd N`. Explicit delegated Agent mode requires both `--agent-adoption-fd N` and `--delegation-record FILE`. N is an integer at least 3. Human and Agent fd options cannot be combined. `session` additionally accepts `--password-fd N` (N an integer at least 3, distinct from the adoption fds): the password is read exactly once from that pipe fd. Password values are never accepted in process arguments, and the Agent stream is never the password channel. The delegation file contains only nonempty `coordinate` and `statement`; it is an explicit embedding claim, not an authenticated grant.
+
+The child owns its inherited adoption read endpoint, a TTY, pipe or socket; a regular file cannot stand in for a live reply channel. It cancels and releases only its own endpoint on completion or abandonment. The parent owns its writer. Both Agent JSONL and adoption endpoints must remain healthy; EOF/error before export terminates the workspace and late replies cannot revive it. There is no default timeout or manufactured reply. A slow active reviewer may continue deciding.
+
+Frames are limited to 1 MiB. At most one complete next frame plus a bounded partial frame is held while an operation is pending; excess pipelining rejects `CLI_INPUT_QUEUE_LIMIT`. Each request id is unique; each interpretation names the one live reply ticket. Reuse or another operation during review rejects. Already-completed synchronous export is not undone by a later EOF.
+
+`verify --bundle DIRECTORY` captures actual bytes, admits them with Core, requires the current private completion marker, and delegates evidence verification to Studio. `read --bundle DIRECTORY [--allow-read] [--judgment N] [--budget BYTES]` first admits its formal Read request, then verifies the current bundle, then invokes public Read. Invalid budgets reject before bundle I/O. Invalid Core bytes or evidence prevent later disclosure; a consistent bundle still needs explicit read permission. Catalog ordinal selection is Host navigation; closure and projection remain in Read.
+
+Private bundles contain `asset.kdna`, `creation-evidence.json`, `binding.json`, `verification.json`, and `complete.json`. The latter is `{kind:'private-studio-export-bundle',version:2}`, carrying a `protection` block when the export was protected. In a protected export the saved-byte completion still runs on the unprotected bytes, but only in an isolated transient area that is removed with the invocation: plaintext never appears at the delivery position, and the delivered `asset.kdna` is the deterministic post-verification derivative (`verification_basis:'pre_protection_plaintext'`) - a `kdna.envelope.aead` container with a password slot (argon2id) and a recovery slot (scrypt-sha256). The recovery code is displayed exactly once on stderr and must not be retained by the host. Static `verify` and `read` do not admit protected containers; consumer-side unlocking belongs to the reader path. A failed protection fails the whole export; Studio/Core protection codes pass through unchanged, and there is no silent fallback to an unprotected bundle. Output reservation is exclusive, saved bytes are re-captured and passed to Studio `completeSave`, then completion is written last. Existing outputs are never replaced. A partial reservation is removed only by its owning invocation. Persistent import/resume, overwritten outputs, external compiler callbacks, signing services, identity verification and action execution are unsupported.
+
+Stdout is private machine JSON and may contain materials, evidence and disclosed content. Stderr contains prompts/previews or concise errors. Do not publish these streams. Errors do not echo raw frames, source paths, stacks or provider secrets. The password read is bounded (64 KiB), strictly UTF-8 with one trailing newline stripped, refuses a TTY fd, and zeroizes its buffer; empty, oversize or invalid-encoding input rejects before any bundle exists. Exit 0 denotes successful export/verification or ready Read; 2 denotes terminal, transport, operation or filesystem rejection; 3 denotes public admission, evidence or disclosure rejection.
+
+Studio format `kdna.studio-creation-evidence/2` and the exact current graph are required. The CLI does not implement another evidence canonicalizer, component interpreter or legacy branch. Static consistency cannot restore `accepted_with_live_context`: static status retains `creation_accepted:not_evaluated`, `live_context:unavailable`, `identity:not_verified` and `action_authorization:not_evaluated`. Role-specific adoption records do not authenticate a person or Agent.
+
+Before executing dependencies, the Host checks every member, path set, package version, mandatory resolution and unbound optional package against `src/public-bindings.json`. Archive equality is a local content observation; installation approval and process-origin trust remain external. Tests use explicit synthetic channels and do not prove actual Agent editorial decisions or publication readiness.
+
+
+## Container support
+
+Studio session output uses container `0.5.0` and Read grammar `0.6.4`.
+The pinned Core/Read implementation versions also contain other public routes;
+sharing their package coordinates does not establish container interchange.
+NativeSections container `0.6.0` / Read `0.7.0` input, another CLI's output,
+persistent import and resume are not supported by this entry. Revisions operate
+on the current live Studio session before final confirmation. `verify` and
+`read` consume this entry's completed bundle under the boundaries above.

package/docs/TERMINAL_AGENT_CREATION.md

@@ -0,0 +1,36 @@
+# Terminal Agent integration
+
+The live private Agent transport creates through Studio; it is not a public asset wire format. Keep stdin/stdout private. The Agent owns substantive authoring and interpretation of actual reviewer language. The CLI has no model or keyword classifier.
+
+Use an approved exact local installation. Start with explicit source files and a new output directory. Use a separately owned fd3 for either `--human-fd 3`, or `--agent-adoption-fd 3 --delegation-record FILE` when the Agent has express editorial authority. Preserve the actual actor. A delegated Agent must never be represented as a human. An interview reads the selected live adoption channel and records question plus answer as private material.
+
+Each newline-terminated Agent frame has unique `id`, `op`, and `data`. Wait for a result or the live reply ticket. The first `ready` event provides the workspace and explicit materials. Material references are one-based ordinals; judgment, alternative and component references use stable local keys.
+
+| op | data |
+| --- | --- |
+| brief | `{title,scope,highest_question}`; the one authored question this judgment answers |
+| interview | `{title,question}` |
+| propose | `{localKey,alternatives:[alternative,alternative,...]}` |
+| revise | `{localKey,baseRevision,alternatives,explanation}` |
+| review | `{}`; request actual selection or final adoption |
+| preview | `{}`; show complete current mapping before final adoption |
+| status | `{}` |
+| export | `{}`; save, re-capture and complete once, then exit; with `--password-fd` the delivered `asset.kdna` is the protected container |
+
+Each alternative has `{localKey,title,subject,scope,statement,rationale,materials:[1]}`. At least two substantive alternatives are required. Optional fields are `method`, `formationRule`, `publicSources`, `publicNotices`; all other fields reject. `materials` is the only CLI adapter, converted to Studio material references. Never send protocol IDs, public profile definitions, native carriers, evidence digests or compiler context.
+
+`method` is `{method:{term},components?,bindings?}`. Its term must be one of the bound Core's published method kinds. A component has `{localKey,type,method:{term},role,content,statement}`; the component's declared basic method equals the judgment term, its role lies in that kind's published role family, and required roles must be covered by non-empty typed content. Content uses the exact current public item/edge/discriminator types. Types are taxonomy, candidate-set and discriminator-set; the latter uses `candidateSetLocalKey` within this judgment. `bindings` remains declared-empty on this path: native bindings are typed edges owned by the graph, not authored links back to the judgment. A missing method rejects (`CREATION_METHOD_REQUIRED`); missing own arrays mean undeclared; explicit `[]` means declared empty; null and owned undefined reject. Core alone determines content interpretation and valid shared grammar.
+
+`formationRule:{conditions:[{kind:'interpreted',statement}]}` makes the authored statement a formation rule rather than an invented fixed result. An explicit empty condition set stays empty. Do not AND candidate-specific conditions into a global prerequisite. Public sources/notices are explicitly authored public identity and notice records, documented by Studio; private source paths and interview bodies must not be automatically published.
+
+During `review`, the CLI emits `adoption_reply` with actual text, the current Studio review and a fresh `replyTo` ticket. Then send one interpretation:
+
+```json
+{"id":"choose-current","op":"interpret","data":{"replyTo":"COPY_CURRENT_TICKET","kind":"select","choices":[{"judgmentLocalKey":"observation","alternativeLocalKey":"preserve"}]}}
+```
+
+Select chooses exactly one current alternative for every group. Other supported kinds are `note`, `reject`, `confirm`, without `choices`. To revise, record the actual feedback, send a current `revise` operation, select again, request a fresh preview, then obtain a fresh final reply. A final confirmation binds the exact current preview, alternatives, context and adoption channel. The Agent interprets real language; it cannot fabricate a reviewer reply, role, message/review id or final digest through its pipe.
+
+The pending review receives its final result after interpretation. There is no separate interpretation success reply. Reusing ids/tickets, changing role/channel, replacing the current review, EOF or input errors reject. Agent termination while waiting abandons the unexported session. Keep one request active; excess queued frames reject. No automatic decision or persistent replay/resume exists.
+
+Export creates one exclusive private bundle and obtains `accepted_with_live_context` only after actual saved-byte readback. Static `verify` always retains `live_context:unavailable` and `creation_accepted:not_evaluated`; it cannot resurrect the capability. Core/Read and static evidence consistency remain separate from actual Agent adoption, verified identity, action permission, Authoring Fit/G4B and publication readiness. Legacy format1 and old completion markers require their original accepted graph and cannot be relabeled current.

package/package.json

@@ -1,39 +1,43 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.10.2",
-  "description": "Official KDNA Studio command-line authoring entry for creating, reviewing, compiling, and exporting .kdna judgment assets through the KDNA toolchain.",
+  "version": "0.13.0-rc.components.2",
+  "description": "Terminal Host for current typed Studio creation and separate human or authorized Agent adoption channels.",
   "type": "commonjs",
   "bin": {
     "kdna-studio": "bin/kdna-studio.js"
   },
   "files": [
-    "bin/",
-    "src/",
+    "bin/kdna-studio.js",
+    "src/terminal-workspace.js",
+    "src/public-bindings.json",
+    "docs/CREATION_COMMAND_CONTRACT.md",
+    "docs/TERMINAL_AGENT_CREATION.md",
     "LICENSE",
     "NOTICE",
-    "README.md"
+    "README.md",
+    "src/component-operations.js"
   ],
   "scripts": {
-    "lint": "node scripts/run-lint.js",
-    "pretest": "node scripts/acquire-trusted-npm-release.js",
-    "test": "node --test tests/*.test.js",
+    "lint": "node --check bin/kdna-studio.js && node --check src/terminal-workspace.js && node --check src/component-operations.js",
+    "test": "node --test tests/current-components/*.test.cjs tests/current/*.test.js",
     "test:all": "node scripts/run-test-all.js",
-    "test:runtime": "node scripts/run-product-tests.js",
-    "test:candidate-chain": "node scripts/verify-runtime-candidate-chain.js",
-    "verify:candidate-sources": "node scripts/verify-runtime-candidate-sources.js",
+    "test:candidate-chain": "node scripts/verify-current-candidate-chain.js",
+    "verify:candidate-sources": "node scripts/verify-current-candidate-sources.js",
     "check:protocol-names": "node scripts/check-current-protocol-names.js",
+    "check:publish-coordinates": "node scripts/check-publish-coordinates.js",
     "release:check": "node scripts/release-check.js",
     "release:generate-evidence": "node scripts/generate-release-evidence.js",
     "release:publish-verified": "node scripts/publish-verified-artifact.js",
-    "prepublishOnly": "node scripts/run-test-all.js && node scripts/verify-runtime-candidate-chain.js && node scripts/release-check.js"
+    "candidate:publish-verified": "node scripts/publish-candidate-artifact.js",
+    "prepublishOnly": "node scripts/check-publish-coordinates.js && node scripts/run-test-all.js && node scripts/verify-current-candidate-chain.js && node scripts/release-check.js",
+    "check:current-bindings": "node scripts/generate-current-bindings.js",
+    "candidate:generate-evidence": "node scripts/generate-candidate-evidence.js"
   },
   "keywords": [
     "kdna",
-    "kdna-studio",
-    "kdna-studio-cli",
-    "authoring",
-    "provenance",
-    "judgment-cards"
+    "agent-native",
+    "creation",
+    "terminal"
   ],
   "license": "Apache-2.0",
   "repository": {
@@ -45,17 +49,24 @@
     "url": "https://github.com/aikdna/kdna-studio-cli/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
-    "@aikdna/kdna-core": "0.20.0",
-    "@aikdna/kdna-studio-core": "2.0.2",
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1",
-    "cbor-x": "^1.6.4"
+    "@aikdna/kdna-core": "0.37.1-rc.browser.1",
+    "@aikdna/kdna-read": "0.11.2-rc.browser.1",
+    "@aikdna/kdna-studio-core": "4.0.0-rc.components.2"
   },
   "directories": {
     "test": "tests"
   },
-  "author": ""
+  "author": "",
+  "overrides": {
+    "fast-uri": "3.1.8",
+    "@aikdna/kdna-core": "$@aikdna/kdna-core",
+    "@aikdna/kdna-read": "$@aikdna/kdna-read",
+    "@aikdna/kdna-studio-core": "$@aikdna/kdna-studio-core"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  }
 }

package/src/component-operations.js

@@ -0,0 +1,13 @@
+"use strict";
+// CLI-only material ordinal adapter. Shared component meaning remains upstream.
+function componentOperations(workspace,materialIds){
+ const fail=code=>{throw Object.assign(new Error(code),{code});};
+ function record(v,keys){if(!v||typeof v!=='object'||Array.isArray(v)||Object.keys(v).some(k=>!keys.includes(k))||keys.some(k=>!Object.hasOwn(v,k)))fail('CLI_COMPONENT_INPUT_INVALID');}
+ function authored(a){if(!a||!Array.isArray(a.materials)||Object.hasOwn(a,'materialRefs'))fail('CLI_COMPONENT_MATERIAL_INVALID');const ids=typeof materialIds==='function'?materialIds():materialIds;const x={...a,materialRefs:a.materials.map(n=>{if(!Number.isSafeInteger(n)||n<1||n>ids.length)fail('CLI_MATERIAL_UNKNOWN');return ids[n-1];})};delete x.materials;return x;}
+ return Object.freeze({
+  propose(data){record(data,['localKey','alternatives']);if(!Array.isArray(data.alternatives))fail('CLI_COMPONENT_INPUT_INVALID');return workspace.agent.propose({localKey:data.localKey,alternatives:data.alternatives.map(authored)});},
+  revise(data){record(data,['localKey','baseRevision','alternatives','explanation']);if(!Array.isArray(data.alternatives))fail('CLI_COMPONENT_INPUT_INVALID');return workspace.agent.revise(data.localKey,{baseRevision:data.baseRevision,alternatives:data.alternatives.map(authored),explanation:data.explanation});},
+  preview(){return workspace.agent.compilePreview();},review(){return workspace.receiveAdoptionReply();},completeSavedReadback(bytes){return workspace.completeSave(bytes);},abort(){return workspace.abort();}
+ });
+}
+module.exports={componentOperations};