feat(cli): add guarded private descriptor transport

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.104
+
+- Add package-owned guarded CLI helpers for create, update, bounded query, and
+  exact readback. Opaque descriptors cross the child-process boundary only
+  through the runtime-owned anonymous process IPC channel; private titles,
+  bodies, tags, selectors, and result proofs stay out of argv, stdin,
+  environment variables, files, stdout, and stderr. The IPC transport works
+  across Bun and Node parents on Linux, macOS, and Windows without Linux
+  `/proc` assumptions or a write-before-connection race.
+- Reject public/body-bearing guarded CLI input, regular-file descriptors,
+  malformed or oversized private frames, replay conflicts, and expired
+  descriptors without echoing private content. Preserve FCAME-1 authority
+  binding, compare-and-swap/create-if-absent semantics, immutable receipts,
+  digest-only proof, exact readback, and same-operation duplicate evidence.
+
 ## 0.2.102
 
 - Republish the same reviewed bounded-query product code through the isolated

README.md

@@ -209,6 +209,47 @@ endpoint never falls back to a collection scan and never returns item bodies or
 titles. `knowledge guarded capabilities --json` reports this private transport
 support without reading configuration, opening a store, or making a request.
 
+When an agent or workflow must cross a process boundary, use the package-owned
+guarded CLI helpers. The caller keeps the private data inside the opaque
+descriptor; the helper creates two anonymous inherited pipes, invokes the
+package CLI with fixed descriptor numbers, and returns only the private
+digest-proof object to the calling process:
+
+```ts
+import {
+  createKnowledgePrivateInputDescriptor,
+  executeKnowledgeGuardedCliWrite,
+} from '@hasna/knowledge';
+
+const privateInput = createKnowledgePrivateInputDescriptor({
+  operation_id: 'doctrine-rollout-2026-08',
+  step_id: 'knowledge-item-one',
+  verb: 'create',
+  target_id: 'hasna-doctrine-one',
+  precondition: { kind: 'absent' },
+  binding,
+  payload: {
+    title: privateReviewedTitle,
+    content: privateReviewedBody,
+    tags: privateReviewedTags,
+  },
+});
+
+const result = await executeKnowledgeGuardedCliWrite(privateInput);
+// result.proof contains IDs, versions, digests, and immutable receipt/replay
+// evidence. It never contains the private title, body, tags, or selector.
+```
+
+Use `executeKnowledgeGuardedCliQuery(...)` for producer-bounded private queries
+and `executeKnowledgeGuardedCliReadback(...)` with a `current_version`
+descriptor for exact readback. The internal
+`knowledge guarded execute-descriptor --ipc` worker accepts private requests and
+results only through the runtime-owned child-process IPC channel. The channel is
+anonymous and cross-platform; no Knowledge value crosses argv, stdin,
+environment variables, files, stdout, or stderr. Direct shell invocation has
+no inherited IPC channel and fails closed. Do not invoke the worker directly or
+hand-roll descriptor materialization.
+
 The deterministic key is:
 
 ```text

bin/knowledge-mcp.js

@@ -14997,7 +14997,7 @@ import { existsSync as existsSync15, readFileSync as readFileSync14, writeFileSy
 // package.json
 var package_default = {
   name: "@hasna/knowledge",
-  version: "0.2.102",
+  version: "0.2.104",
   description: "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   type: "module",
   exports: {

dist/guarded-cli.d.ts

@@ -0,0 +1,29 @@
+import { KNOWLEDGE_GUARDED_WRITE_CONTRACT, type KnowledgePrivateInputDescriptor, type KnowledgePrivateQueryDescriptor, type KnowledgePrivateResultProof } from './guarded-write-contract.js';
+export declare const KNOWLEDGE_GUARDED_CLI_REQUEST_SCHEMA: 'knowledge.guarded-cli-request.v1';
+export declare const KNOWLEDGE_GUARDED_CLI_RESULT_SCHEMA: 'knowledge.guarded-cli-result.v1';
+type KnowledgeGuardedCliAction = 'write' | 'query' | 'readback';
+type KnowledgeGuardedCliTransport = 'process_ipc' | 'anonymous_fd';
+export interface KnowledgeGuardedCliPrivateResult {
+    schema: typeof KNOWLEDGE_GUARDED_CLI_RESULT_SCHEMA;
+    ok: true;
+    contract: typeof KNOWLEDGE_GUARDED_WRITE_CONTRACT;
+    action: KnowledgeGuardedCliAction;
+    transport: KnowledgeGuardedCliTransport;
+    request_digest: string;
+    result_digest: string;
+    proof: KnowledgePrivateResultProof;
+}
+export interface KnowledgeGuardedCliDescriptorOptions {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+export declare class KnowledgeGuardedCliDescriptorError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function runKnowledgeGuardedCliDescriptorWorker(requestFd: number, resultFd: number, env?: NodeJS.ProcessEnv): Promise<Omit<KnowledgeGuardedCliPrivateResult, 'proof'>>;
+export declare function runKnowledgeGuardedCliIpcWorker(env?: NodeJS.ProcessEnv): Promise<Omit<KnowledgeGuardedCliPrivateResult, 'proof'>>;
+export declare function executeKnowledgeGuardedCliWrite(descriptor: KnowledgePrivateInputDescriptor, options?: KnowledgeGuardedCliDescriptorOptions): Promise<KnowledgeGuardedCliPrivateResult>;
+export declare function executeKnowledgeGuardedCliQuery(descriptor: KnowledgePrivateQueryDescriptor, options?: KnowledgeGuardedCliDescriptorOptions): Promise<KnowledgeGuardedCliPrivateResult>;
+export declare function executeKnowledgeGuardedCliReadback(descriptor: KnowledgePrivateQueryDescriptor, options?: KnowledgeGuardedCliDescriptorOptions): Promise<KnowledgeGuardedCliPrivateResult>;
+export {};

dist/index.d.ts

@@ -5,6 +5,7 @@ export { type KnowledgeItem, type Store as KnowledgeItemStoreFile, } from './sto
 export { KNOWLEDGE_APP_SLUG, KNOWLEDGE_BOUNDED_QUERY_CAPABILITY, KNOWLEDGE_RESOURCE, KnowledgeBoundedQueryCapabilityError, isKnowledgeApiMode, resolveKnowledgeCloudStore, type KnowledgeCloudStore, type KnowledgeCloudCreateInput, type KnowledgeCloudListOptions, type KnowledgeCloudPatch, type KnowledgeCloudSearchHit, type KnowledgeCloudSearchOptions, } from './cloud-store.js';
 export { DEFAULT_KNOWLEDGE_GUARDED_LIMITS, KNOWLEDGE_GUARDED_WRITE_CONTRACT, KNOWLEDGE_PRIVATE_INPUT_SCHEMA, KNOWLEDGE_PRIVATE_QUERY_SCHEMA, KNOWLEDGE_PRIVATE_RESULT_SCHEMA, KNOWLEDGE_PRIVATE_TITLE_LOOKUP_SCHEMA, KNOWLEDGE_RELATIONS_METADATA_KEY, KNOWLEDGE_RELATIONS_SCHEMA, assertKnowledgeGuardedBinding, assertKnowledgeGuardedBounds, assertKnowledgeGuardedManifestBinding, assertKnowledgeGuardedManifestOptions, assertKnowledgeGuardedManifestTerminalCompleteness, assertKnowledgeGuardedPayload, assertKnowledgeGuardedPrecondition, assertKnowledgePrivateQueryBounds, assertKnowledgePrivateQueryPage, assertKnowledgePrivateQuerySelector, assertKnowledgeRelationsMetadata, assertKnowledgeTerminalCompleteness, canonicalKnowledgeGuardedJson, computeKnowledgeGuardedAdoptionDeterministicKey, computeKnowledgeGuardedAdoptionReceiptId, computeKnowledgeGuardedDeterministicKey, computeKnowledgeGuardedManifestId, computeKnowledgeGuardedManifestDeterministicKey, computeKnowledgeGuardedManifestDigest, computeKnowledgeGuardedReceiptId, computeKnowledgeGuardedRecoveryKey, createKnowledgePrivateInputDescriptor, createKnowledgePrivateQueryDescriptor, createKnowledgePrivateTitleLookupDescriptor, evaluateKnowledgeGuardedManifestCompletion, knowledgeGuardedDigest, knowledgeGuardedContentSha256, knowledgeGuardedUtf8Bytes, inspectKnowledgePrivateResult, normalizeKnowledgeGuardedLimits, revokeKnowledgePrivateInputDescriptor, revokeKnowledgePrivateQueryDescriptor, revokeKnowledgePrivateResultDescriptor, revokeKnowledgePrivateTitleLookupDescriptor, type CreateKnowledgeGuardedManifestOptions, type CreateKnowledgePrivateInputDescriptorOptions, type CreateKnowledgePrivateQueryDescriptorOptions, type CreateKnowledgePrivateTitleLookupDescriptorOptions, type KnowledgeAuthorityBinding, type KnowledgeAuthorityClassification, type KnowledgeGuardedAdoptionAction, type KnowledgeGuardedAdoptionEnvelope, type KnowledgeGuardedAdoptionKeyInput, type KnowledgeGuardedAdoptionReceipt, type KnowledgeGuardedAdoptionReconciliation, type KnowledgeGuardedAdoptionResult, type KnowledgeGuardedAdoptionSubmission, type KnowledgeGuardedBinding, type KnowledgeGuardedBindingState, type KnowledgeGuardedBindingStateReadback, type KnowledgeGuardedBounds, type KnowledgeGuardedCreatePayload, type KnowledgeGuardedDeterministicKeyInput, type KnowledgeGuardedLimits, type KnowledgeGuardedManifest, type KnowledgeGuardedManifestBinding, type KnowledgeGuardedManifestCompletion, type KnowledgeGuardedManifestEnvelope, type KnowledgeGuardedManifestReconciliation, type KnowledgeGuardedManifestReconciliationStep, type KnowledgeGuardedManifestRecovery, type KnowledgeGuardedManifestStep, type KnowledgeGuardedManifestStepState, type KnowledgeGuardedManifestSubmission, type KnowledgeGuardedLegacyAdoptionOptions, type KnowledgeGuardedLegacyRollbackOptions, type KnowledgeGuardedPayload, type KnowledgeGuardedPrecondition, type KnowledgeGuardedReadback, type KnowledgeGuardedReceipt, type KnowledgeGuardedReceiptStatus, type KnowledgeGuardedRecoveryKeyInput, type KnowledgeGuardedRecoveryStrategy, type KnowledgeGuardedRollbackResult, type KnowledgeGuardedSubmission, type KnowledgeGuardedTitleLookup, type KnowledgeGuardedUpdatePayload, type KnowledgeGuardedWriteEnvelope, type KnowledgeGuardedWriteResult, type KnowledgeGuardedWriteVerb, type KnowledgePrivateInputDescriptor, type KnowledgePrivateItemProof, type KnowledgePrivateQueryArchive, type KnowledgePrivateQueryBounds, type KnowledgePrivateQueryDescriptor, type KnowledgePrivateQueryEnvelope, type KnowledgePrivateQueryItemProof, type KnowledgePrivateQueryKind, type KnowledgePrivateQueryPage, type KnowledgePrivateQueryResult, type KnowledgePrivateQuerySelector, type KnowledgePrivateResultDescriptor, type KnowledgePrivateResultProof, type KnowledgePrivateTitleLookupDescriptor, type KnowledgeRelationsMetadata, type KnowledgeTerminalReconciliation, } from './guarded-write-contract.js';
 export * from './guarded-writer.js';
+export { KNOWLEDGE_GUARDED_CLI_REQUEST_SCHEMA, KNOWLEDGE_GUARDED_CLI_RESULT_SCHEMA, KnowledgeGuardedCliDescriptorError, executeKnowledgeGuardedCliQuery, executeKnowledgeGuardedCliReadback, executeKnowledgeGuardedCliWrite, type KnowledgeGuardedCliDescriptorOptions, type KnowledgeGuardedCliPrivateResult, } from './guarded-cli.js';
 export { KNOWLEDGE_API_KEY_ENV_KEYS, KNOWLEDGE_API_URL_ENV_KEYS, KNOWLEDGE_MODE_ENV_KEYS, LOCAL_MODE_CANDIDATES, SERVER_MODE_CANDIDATES, contractsStorageModeFor, knowledgeModeReport, localStorageMode, pinnedTransportEnv, resolveKnowledgeModeSelection, serverStorageMode, type KnowledgeMode, type ModeNormalizer, type KnowledgeModeReport, type KnowledgeModeResolution, type KnowledgeModeSource, } from './knowledge-mode.js';
 export { NETWORK_GUARD_ENV, KnowledgeNetworkGuardError, assertOutboundRequestAllowed, guardedFetch, isLoopbackHostname, isNetworkGuardActive, } from './net-guard.js';
 export { buildKnowledgeAgentContextPack, type KnowledgeAgentContextCitation, type KnowledgeAgentContextEvidence, type KnowledgeAgentContextPack, type KnowledgeAgentDuplicateCandidate, type KnowledgeContextPackPurpose, type KnowledgeContextPackSource, } from './context-pack.js';