cameron.stream / thought-stream
A local-first event pipeline for independent agents, built on Jazz.
Star
Fork 0
Watch
thought-stream spec public-knowledge.md
7.7 kB
Markdown
at document-workbench

Coil Public Knowledge proposals #

Boundary #

The Coil consumer turns one exact eligible Coil document version into a private, inert Public Knowledge diff proposal. It does not declassify, stage, edit, publish, deploy, or write ATProto records.

The authority chain is:

Coil file event → default-deny host admission → proposal-only Co/Luna turn → controller-owned tool validation → sensitive Jazz proposal

The current implementation stops there. A future materializer must be a separate process that consumes an append-only human decision, revalidates the complete proposal and exact catalog base, writes only to a configured staging surface, and leaves publication to the existing reviewed Public Knowledge pipeline. No materializer or publisher may subscribe directly to the agent proposal event.

Source admission #

The consumer subscribes to one concrete sensitive Coil filesystem source. Before an SDK session exists, the trusted parent:

  1. resolves the event-bound document id, path, immutable version, and SHA-256 from Jazz;
  2. applies the configured default-deny path policy;
  3. rejects deleted, blocked, deferred, unsupported, stale, or oversized input;
  4. reads the configured public catalog through regular nonsymlink Markdown files confined to its real root;
  5. records one catalog digest over slug, public metadata, and content hash;
  6. admits a bounded deterministic set of lexically relevant existing entries, including their exact current public body and SHA-256.

All catalog slugs remain available for collision and related-link checks. Only admitted entries may be replacement targets. The context snapshot records their slugs and hashes. A target body that does not fit the packet budget is not admitted and cannot be revised in that run.

Blocked source content is never read. Policy-blocked wikilinks remain explicit privacy evidence. A skipped input advances only this consumer's source progress and creates no conversation or inference reservation.

Proposal-only Agent SDK profile #

Each stable Coil documentId owns one durable conversation on Co's existing agent id. The declaration fixes Luna as the model and uses the local API-backed Agent SDK profile so Co's memory remains available. Local execution is accepted only with:

  • outputOnly: true and proposalTool: public-knowledge-diff;
  • strict permission mode;
  • an exact client-tool allowlist containing only submit_public_knowledge_diff;
  • exactly one controller-owned tool definition with that name;
  • no Patch, Write, Bash, MCP servers, repositories, or workspace resources;
  • no skills;
  • dreaming off;
  • the SDK-owned filesystemConfinement: memory profile rooted at Co's configured memory tree;
  • strict proposal-schema validation.

The turn may read the supplied Coil packet and Co memory. It has no Jazz, Coil, site, Git, channel, deploy, or publication handle. submit_public_knowledge_diff captures one candidate in controller memory, validates it against the exact output contract and current context, and returns only a compact acceptance or error acknowledgment. Its callback does not write Jazz or any filesystem, Git, PDS, site, channel, deploy, or publication surface.

Exactly one valid call and one successful correlated result are required. Zero calls, duplicate calls, malformed arguments, context-invalid targets, unknown tools, missing results, and tool errors fail the run before semantic settlement. Tool arguments and result bodies remain absent from traces. Missing kernel confinement, memory root, agent route, or proposal-only declaration invariants fail before source progress advances.

Proposed-diff contract #

submit_public_knowledge_diff accepts exactly one bounded raw string. That string must decode to one object satisfying stream.thought.output.public-knowledge-proposed-diff@1. The transport envelope avoids provider-specific nested-tool-schema failures; it does not weaken semantic validation. The trusted runner uses the decoded, captured, validated object as semantic AgentOutput; the model's final PROPOSAL_CAPTURED acknowledgment is not parsed as the proposal.

Every proposal-tool call contains:

  • literal proposalState: agent-proposed;
  • decision: propose-new, revise-existing, or skip;
  • bounded summary and rationale;
  • either one proposal or null;
  • public-source verification requests and private-dependency notes;
  • privacy status/findings and bounded confidence;
  • literal publicationEligible: false.

A proposal contains one target and one draft:

  • new target: kind: new, an absent slug, and baseSha256: null;
  • replacement target: kind: replacement, one context-admitted slug, and its exact current SHA-256;
  • draft: title, summary, document kind, topics, related slugs, and a bounded Markdown body without frontmatter.

The trusted parent revalidates decision/shape agreement, slug collision or exact target admission, base hash, related slugs, blocked-wikilink privacy, and the literal nonpublication flag. privacy.status: blocked requires skip with no proposal. Unknown targets, stale hashes, malformed bodies, or model-added fields fail the run and emit no semantic output.

Jazz event #

A valid result settles as stream.thought.agent.public-knowledge-diff.proposed@1 with sensitive privacy, exact source/run/context lineage, the frozen output-contract identity, and the canonical structured output. The event is the suggestion and proposed diff. It is not a review receipt, decision, source mutation, stage command, publication authorization, or egress request.

The former stream.thought.derived.public-knowledge.recommendation@1 remains registered for historical readback. New declarations cannot emit it.

Recovery and activation #

Conversation bindings remain stable across confident path renames. The declaration version and output contract are part of retry-stable execution identity. If the remote turn completes before Jazz settlement, bounded conversation-history recovery reconstructs exactly one named tool call, requires its successful correlated tool return and final acknowledgment, revalidates the arguments, and settles without resending. Ambiguous, duplicate, malformed, or incomplete history fails closed.

Version 3 starts with replay now; activation must initialize progress at the observed Coil source head and verify zero v3 runs before the producer resumes. Existing version 2 recommendation evidence is not reinterpreted as a proposed diff.

Activation may enable private proposal generation only. It must not add a materializer, site writer, publisher, deployment step, or public notification.

Proof #

Tests must cover:

  • blocked-path rejection before document reads and inference accounting;
  • bounded relevant-target body admission and unrelated-body exclusion;
  • catalog collision, unknown target, stale base hash, unknown related slug, and blocked privacy rejection;
  • new, replacement, and skip schema invariants;
  • explicit proposal-only declaration and session options with exactly one fixed client tool;
  • successful one-call capture whose final acknowledgment is ignored as semantic output;
  • zero, duplicate, malformed, unknown, context-invalid, missing-result, and error-result tool failures;
  • content-dark tool-call and tool-result traces;
  • exact proposal-tool recovery from bounded conversation history without resending;
  • stable per-document conversation recovery;
  • sensitive proposal event settlement and absence of direct materialization/publication code paths;
  • credential compartments keeping the configured Co memory root only in the consumer process and excluding it from every other service compartment, receipt value, event, trace, and prompt.