@jangts/agent-core 0.2.0 → 0.2.1

package/development/docs/knowledge.en.md

@@ -0,0 +1,89 @@
+# Knowledge documents, sections, and versions
+
+[Back to development handbook](README.md) · [Knowledge API](api/knowledge-answering.md#knowledge) · [Complete answering chain](api/knowledge-answering.md)
+
+## How the library learns your knowledge structure
+
+Core does not scan knowledge directories, infer a knowledge base from file names, or automatically generate sections from Markdown headings. The App explicitly executes the following chain:
+
+```text
+App reads controlled sources
+  → provides id, revision, locale, and body/structure
+  → Knowledge.parseKnowledgeDocument (only when text anchors are used)
+  → Knowledge.defineKnowledgeCatalog
+  → App checks the task's document/section references
+  → catalog.read with the reads allowed for this round
+  → passes the KnowledgeSnapshot as evidence to subsequent handlers
+```
+
+This structure is a local specification after adopting the Knowledge Kit, not a document format every Agent must store. The App can generate `KnowledgeDocument.parts` directly without Markdown parsing.
+
+## Development-time preparation tools and runtime assembly functions
+
+| Entry/asset | Purpose | What it does not do |
+| --- | --- | --- |
+| [Maintenance guide](maintenance.md) | Prepare knowledge in the project; organize faithfully when sources exist, keep empty when none | Knowledge must have real sources; ideas are not facts |
+| `Knowledge.parseKnowledgeDocument({id, revision, text, locale?})` | Parse paired section anchors into a document tree | Does not read files, compute revision, or complete all catalog validation |
+| `Knowledge.defineKnowledgeCatalog(documents, options?)` | Compile/freeze an in-memory document catalog, providing ids, sectionIds, assertSelection, read | Does not create databases, watch files, import uploads, or automatically learn or write back |
+| [Section marker notes](#text-section-anchors) | Local code fragment explaining paired anchors and nesting rules | Not initial knowledge and not loaded automatically |
+| [knowledge.mjs](../skills/agent-core-app/scripts/lib/knowledge.mjs) | App-side template shipped with the Skill for explicitly reading files, computing versions, and compiling catalogs | Not a built-in persistent initializer of the library |
+
+Minimal document JSON structure:
+
+```json
+{
+  "id": "service-guide",
+  "revision": "content-version-1",
+  "locale": "zh-CN",
+  "parts": [
+    "全局引言。",
+    { "id": "delivery", "parts": [
+      "本章节自身正文。",
+      { "id": "delivery.timing", "parts": ["时机说明。"] }
+    ] }
+  ]
+}
+```
+
+`parts` may mix raw text strings and subsections. Structured section IDs must be non-empty strings and **globally unique within the same document**, not merely unique among adjacent siblings. Document IDs are unique within the catalog; catalog compilation rejects duplicate sections and cycles. Do not run only the text parser and skip catalog compilation.
+
+## Text section anchors
+
+Sources use paired markers on their own lines, with no indentation:
+
+```md
+<!-- agent-section:delivery -->
+本章节自身正文。
+<!-- agent-section:delivery.timing -->
+子章节正文。
+<!-- /agent-section:delivery.timing -->
+<!-- /agent-section:delivery -->
+```
+
+The characters accepted in IDs by the text adapter are English letters, digits, `_`, `.`, `:`, and `-`. Markers must keep spaces as in the example and occupy their own line; opening and closing IDs must match and nest correctly. Markdown `#` headings are merely body text. The parser recognizes anchors from raw text and is not a full Markdown interpreter; do not put example anchors on their own lines inside code fences in sources, or they will also be recognized as real sections.
+
+Stable IDs represent content identity. Changing a title does not require changing the ID; when splitting/deleting sections, migrate task mappings and historical reference policies at the same time. Characters such as `.` are only part of the ID; parent-child relationships are determined by the actual nesting in `parts` and cannot be guessed from names.
+
+## Three ways to read
+
+| Request | Returned scope |
+| --- | --- |
+| `{documentId:'service-guide', selection:{mode:'document'}}` | The whole body text and all descendants, in source order |
+| `{documentId:'service-guide', selection:{mode:'self', sectionIds:['delivery']}}` | The selected section's own string body, excluding subsections |
+| `{documentId:'service-guide', selection:{mode:'subtree', sectionIds:['delivery']}}` | The selected section and all its descendants |
+
+Sections explicitly selected are joined by two newlines in the order of the request array; duplicate IDs are rejected. If a parent section and its child are both selected into a subtree as two different IDs, the child text may still be included twice; the library does not automatically eliminate this ancestor overlap. The App should choose the appropriate minimal complete scope.
+
+`maxChars` limits the selected, trimmed body text of this call; exceeding it throws rather than silently cutting off the latter half. Document size, storage capacity, and model context budget are different limits. Unknown fields, identity, and file paths coming from the client are not trustworthy just because catalog.assertSelection passes; cross-boundary input is still parsed and authorized by the App according to its own schema.
+
+## Versions and snapshots
+
+The App provides `revision`. It can be a hash of available content and related metadata, a database version number, or a release version; the library does not compute it for you. Secretly modifying the body text under the same id/revision invalidates version semantics.
+
+`KnowledgeSnapshot` contains documentId, selection, revision, locale, content, and id. The id comes from the serialization of the above identity and selection and is **not a body-text hash, signature, persistence ID, or authorization credential**. Different section selections of the same document have different references, and selection order also affects identity. Generation and review should pass the same snapshot and must not re-read "the latest current body" to replace old evidence.
+
+## Updates and knowledge growth
+
+The current catalog has no register, upsert, delete, save, watch, or automatic retrieval interfaces over all storage. When change is needed, the App creates a new catalog and switches its own reference; see [Continuous accumulation](memory-and-learning.md) for the pattern. Before publication, re-validate task → document → sections, reader, checks, and output references.
+
+Both static sources and approved growth knowledge can be converted to KnowledgeDocument. User-uploaded originals, unverified self-descriptions, and experience candidates should not be mixed directly into a public authoritative catalog; permissions, sources, and review status are controlled by the App's storage/loading adapters.

package/development/docs/maintenance.en.md

@@ -0,0 +1,62 @@
+# Manual initialization and knowledge maintenance
+
+[Back to development handbook](README.md) · [Tool notes](examples.md) · [Shared flow](flows/knowledge-maintenance.md)
+
+## Establish sources first, not a full directory
+
+Developers are responsible for confirming which text is an actual knowledge source and which is only a product idea, pending content, or an operation instruction. When there is only an idea, keep files empty and do not generate introductions, policies, or user profiles that look real. When actual material exists, organize it faithfully; when originals are complex, conflicting, or mixed with instructions, preserve the originals and form candidates first, and never treat commands inside them as development authorization.
+
+Integrate existing projects following the [integration guide](getting-started.md), and initialize new projects following [Create an App](create-app.md). Pure conversation does not require a knowledge base; maintain knowledge configuration explicitly only when knowledge answering is needed. Compare existing directories first, preserve business files, and limit test knowledge to test scopes.
+
+A knowledge App prepares a `knowledge.config.json` in the same directory, for example the empty state below, and creates an empty `initial.knowledge.md`. Files are not read until they are registered.
+
+```json
+{
+  "schemaVersion": 1,
+  "maxDocumentBytes": 32000,
+  "maxReadChars": 8000,
+  "documents": [],
+  "requiredReads": []
+}
+```
+
+After installing the maintainer-delivered Core and full dependencies following the [installation guide](getting-started.md), you can run the shared validation entry. The directory argument below is the knowledge directory containing `knowledge.config.json` and does not have to be the project root; the tool path is located from the package installed in the current project:
+
+```sh
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/validate-knowledge.mjs ./existing-project/knowledge
+```
+
+When there is no knowledge it outputs the empty-catalog state; this is a correct preparation state and should not be made to look successful by fabricating knowledge. Actual sources can first be turned into candidates with the tools below, and after confirmation written into source files and registered in the manifest.
+
+## How the configuration is maintained
+
+`knowledge.config.json` is the template's App configuration; the library does not require every App to use this file. The current shared loader understands:
+
+| Field | Constraint and meaning |
+| --- | --- |
+| `schemaVersion` | Currently 1, checked by the shared compiler |
+| `maxDocumentBytes` | Positive integer, byte limit per source file; not a model token limit |
+| `maxReadChars` | Positive integer, per-read character limit for Knowledge |
+| `documents` | May be empty; entries are `{id,file,locale?}`; currently only lowercase `*.knowledge.md` file names in the same directory are allowed, and model-supplied paths are not accepted |
+| `requiredReads` | `{documentId,selection}` actually depended on by tasks; all references are checked at compile time |
+
+Document IDs must be unique; see [Knowledge documents](knowledge.md) for section rules. Newly added files must be registered explicitly; being on disk does not automatically grant publication or read eligibility. Source and subsequent version traceability are carried by the maintainer's own change records; candidate tools do not replace complete publication records.
+
+## Adding and updating reuse the same validation
+
+```sh
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/prepare-source.mjs ./existing-project/knowledge --source ./revision.md --id initial-doc
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/validate-knowledge.mjs ./existing-project/knowledge
+```
+
+The first command only generates a candidate; the second checks the **currently effective configuration** and does not publish the candidate. The candidate contains the original file, document ID, suggested addition/replacement, source hash, revision, as well as the configuration hash at preparation time and existing document versions. Candidate validation also checks existing required section references; deleting a referenced section fails, and the task and configuration must be explicitly adjusted and the candidate prepared again—errors cannot be skipped automatically.
+
+The configuration hash comes from the raw bytes actually parsed this time, sharing a single configuration read with the candidate's budget and required-read validation, so it is not re-read after validation and marked against a different baseline. Each source file version comes from content read this time; this does not constitute an atomic multi-file filesystem snapshot.
+
+Publication is done by the maintainer: verify sources, body diffs, task references, and permissions → save the candidate to a controlled source file → add the new document to the manifest or update an existing file → use the same check entry → publish one complete version. Before publishing, compare the effective configuration and the revisions of replaced documents against the candidate baseline; if stale, redo the comparison. A single-file write is not a multi-file transaction; production systems should use their own versioned publication, transactions, or atomic switching.
+
+Direct editing follows the same flow. A failed validation keeps the published version; generation and review use the same snapshot; a failed update does not delete the original file. Manual and runtime growth can share `compileApplicationKnowledge`, replacing only the input and commit adapters.
+
+## What maintenance does not happen automatically
+
+The tools have no automatic approval, publication, file watching, indexing, scheduled learning, or database writes. User profiles and business experience are different application data; define their sources, updates, and deletions according to [Continuous accumulation](memory-and-learning.md), then decide whether to convert them into readable Knowledge documents.

package/development/docs/materials.en.md

@@ -0,0 +1,38 @@
+# User materials and data boundaries
+
+[Back to development handbook](README.md) · [Continuous accumulation](memory-and-learning.md)
+
+Receiving material, extracting body text, using it within a round, storing it in a personal profile, and publishing it as shared knowledge are different operations. Core does not automatically convert uploads into long-term memory, nor does it trust instructions in material just because the material contains section anchors.
+
+## Minimal processing chain
+
+```text
+Server confirms identity and material ownership
+  → App checks format/size, saves necessary source information
+  → Controlled parser extracts body text, records extraction failures or gaps
+  → Selects content according to this round's authorization
+  → Support context fragment marks it as user data and sets a budget
+  → Handler uses the material and binds output to actual evidence
+```
+
+Parsing and saving are provided by App adapters. The plain text example does not mean PDF, image OCR, audio transcription, web crawling, or archives are supported. When these formats are needed, register parsing capabilities and acceptable results explicitly; parsing failure must not be treated as empty content and then followed by a complete conclusion.
+
+| Field to be made explicit | Purpose |
+| --- | --- |
+| Material ID, owning user/tenant, access scope | The server establishes permissions and does not trust client-claimed owners |
+| Original reference, type, source time, content hash | Retrieve the original and determine versions; do not treat file names as stable identity |
+| Extraction version, body text, gaps, and parsing status | Distinguish originals from model/parser output |
+| Lifecycle, retention, and deletion method | Whether this round, the session, or persistent storage is decided by the product |
+| Review/publication status | Candidate material cannot automatically become shared authoritative knowledge |
+
+See [Material record](records.md#material-record) for a reference. It is an App-owned record sample with no corresponding Core persistence API.
+
+## Context and tools
+
+Use Support fragments to note the real source, `trust: 'user'`, and the corresponding lifecycle. The trust label is part of the assembly contract, not a sandbox; the App still needs to prevent material body text from being treated as higher-privilege instructions or executable code. Do not dynamically add one executable tool per uploaded file; usually keep a controlled `material.read` whose parameters reference IDs authorized for this round.
+
+When continuing use across rounds, pass only references available to the session and re-confirm permissions and lifecycle. When persistent storage is needed, enter the application's own candidate and publication flow. After deleting an original, also clean up extracted text, summaries, indexes, and references according to the App policy—do not delete only the UI list.
+
+## Delivery limits
+
+Do not output the full material text by default in errors, logs, or receipts. Partial reads, insufficient budget, and incomplete parsing should become explicit check results; retries cannot widen the visible scope. Source references, file download URLs, and cross-end presentation are chosen by the App; the Interaction Kit is optional, and front and back ends are not forced to use InteractionProtocol/CommandCatalog uniformly.

package/development/docs/mechanisms.en.md

@@ -0,0 +1,227 @@
+# How the mechanism works
+
+[Back to development handbook](README.md) · [API handbook](api/README.md) · [Knowledge answering contract](api/knowledge-answering.md)
+
+This document explains the current implementation with diagrams. Flows labeled "App composition example" are explicitly orchestrated by the application, not a fixed Agent flow built into Core; Core does not require the App to use Support, Kit, or task decomposition.
+
+## 1. Overall collaboration relationship
+
+```mermaid
+flowchart LR
+    User[User input] --> App[App: identity, configuration, business orchestration and delivery]
+    App -->|calls runtime APIs, registers handlers| Core[Core: execution, model, tools, context contracts]
+    Core -->|calls back according to registered contracts| Handler[App handler: business processing and actual ports]
+    Handler -->|state updates, results or errors| Core
+    App -->|optional integration assistance| Support[Support: builds configuration, adapters and handlers]
+    Support -->|artifacts handed to the App for registration| App
+    Handler -->|calls as needed| Kit[Optional Kit: knowledge, answering, presentation, interaction, etc.]
+    Kit -->|local business results| Handler
+    Handler --> IO[App databases, files and external services]
+    Core -->|ChatProvider contract| Provider[Model connection provided by the App]
+    Provider --> Model[Model service]
+    App --> Output[User-visible output]
+```
+
+Core and App have a call/callback relationship. Support assists the App in integrating the same set of contracts; Kit is chosen one-way by the App, and a Kit may call Core APIs internally, still bound by the same budget, cancellation, and error contracts.
+
+## 2. How task concepts map to execution mechanisms
+
+```mermaid
+flowchart TD
+    Question[User question] --> Compose[App organizes this round's processing by business]
+    Catalog[Central capability manifest: purpose, schema, constraints, handler] --> View[Capability view visible this round]
+    Identity[Server-side identity and resource permissions] --> View
+    View --> Compose
+    Compose --> Workflow[Optional AgentWorkflow: declares execution nodes and routing]
+    Workflow --> Node[Node: requires, run, provides, routes, onErrorNodeId]
+    Node --> Handler[App handler]
+    Handler --> Model[ModelRunner: obtains model proposals or answers]
+    Handler --> Tool[ToolRegistry: executes registered tools]
+    Handler --> Tasks[Optional Answering: domain answering tasks]
+    Tasks --> Definition[Task declaration: id, inputSchema, readerId, outputId, checkIds, intentIds, scopeId]
+    Definition --> Evidence[App reader: authorization, actual reading and evidence]
+    Evidence --> Items[AnswerItem: source status and owning input ID]
+    Items --> Answer[Generation, checks, local repair and delivery status]
+    Model --> Update[Handler returns results or local state updates]
+    Tool --> Update
+    Answer --> Update
+    Update --> Route[Core commits compliant updates, then selects a route per declarations]
+    Route -->|continue| Node
+    Route -->|complete| Result[Return to App for delivery]
+```
+
+The three concepts here are different: the **user question** is input, a **workflow node** is an execution stage, and an **answering task/item** is a domain object of the Answering Kit. One node can process multiple answer items; model proposals do not automatically create workflow nodes or install new handlers. A basic `ModelRunner.invoke` call needs neither a workflow nor answering tasks.
+
+## 3. How a Core workflow advances
+
+Corresponds to the actual rules of `AgentWorkflow` and a bound `AgentCoreEngine.run`.
+
+```mermaid
+flowchart TD
+    Definition[App declares workflow manifest] --> Validate[Validate on construction: nodes, route references, reachability, bounded cycles]
+    Validate --> Entry[entryNodeId corresponds to a startsRound node]
+    Entry --> Abort[Check cancellation, obtain target node]
+    Abort --> Round{Node marked startsRound?}
+    Round -->|yes| Budget{Enough round budget?}
+    Budget -->|no| Exhaust[Throw budget exhausted error]
+    Budget -->|yes| Count[Consume one round]
+    Round -->|no| Enter[Emit enter event]
+    Count --> Enter
+    Enter --> Requires[Check requires fields]
+    Requires --> Run[Call node run, obtain local updates]
+    Run --> Commit[Check cancellation, update shape and provides, then commit updates]
+    Commit --> Select[Select the first match in routes order]
+    Select --> Route{Match result}
+    Route -->|target node| Transition[Emit transition, clear previous node error]
+    Transition --> Abort
+    Route -->|complete| Complete[Compute result, isResult, check cancellation]
+    Complete --> End[Emit complete and return]
+    Route -->|no match| Contract[Workflow contract error]
+    Requires -.->|exception| Error[Error handling within the node try scope]
+    Run -.->|exception| Error
+    Commit -.->|exception| Error
+    Complete -.->|exception| Error
+    Contract --> Error
+    Error --> Recover{Not cancelled, not a contract error, and onErrorNodeId present?}
+    Recover -->|yes| ErrorNode[Move to the error node with context.error]
+    ErrorNode --> Abort
+    Recover -->|no| Throw[Throw to the caller]
+```
+
+Only entering a node with `startsRound: true` consumes a round; other stages in the same round do not count separately. Every possible cycle (including error routing) must pass through a round boundary. When the entry node omits the field, it starts a round by default. The budget entry check is outside the node's try scope, so exhaustion is not routed to that node's onErrorNodeId. `run(step)` uses an explicit StepOutcome: `{ type: 'continue' }` to continue, `{ type: 'complete', value }` to complete; value may legitimately be undefined.
+
+The commit guard covers only local state updates managed by Core; it does not roll back external writes that the handler has already performed. A failed diagnostic observation does not change business execution.
+
+## 4. Timing from model proposal to actual tool execution
+
+**App composition example**: uses the Support tool catalog, ModelRunner, and the Core tool executor.
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant A as App orchestration
+    participant S as Support tool catalog
+    participant M as ModelRunner
+    participant P as ChatProvider / model
+    participant T as Core ToolRegistry
+    participant H as App tool handler
+    U->>A: asks a question
+    A->>S: Obtains capability view and in-request runtime from the same manifest
+    S-->>A: Model declarations, parsers, real execution registration
+    A->>M: invoke (input and registered transport)
+    M->>M: Check cancellation, call quota, input and schema budget
+    M->>P: stream (input and visible capabilities)
+    P-->>M: Model chunks
+    M->>M: Full collection, protocol parsing
+    M-->>A: ToolProposal (tool name and raw parameters)
+    A->>T: runtime.invoke (tool name, parameters)
+    T->>T: Look up registered tool, parseInput
+    T->>H: authorize (parameters, server-side context, signal)
+    alt Authorization passes
+        H-->>T: Allowed
+        T->>H: execute, and wait for actual I/O
+        H-->>T: Actual result
+        T->>T: parseOutput, record success event
+        T-->>A: Validated result
+        opt App needs to continue generation based on the result
+            A->>M: invoke (tool result and follow-up input)
+            M->>P: Generate within the remaining quota
+            P-->>M: Complete response
+            M-->>A: Parsed result
+        end
+        A->>A: Business checks, bind facts and deliver
+        A-->>U: Final reply
+    else Authorization denied or execution/output check fails
+        H-->>T: Denied or exception
+        T-->>A: Error and failure event
+        A-->>U: App handles the failure according to the actual cause
+    end
+```
+
+The error branch in the diagram also covers input/output check failures in the Registry itself, where a handler call may not occur. A model proposal is not a success receipt, and Core does not automatically execute a tool just because the model proposed its name; whether to call it subsequently, generate again, or end is decided by the App handler/workflow. A failed tool output check also does not mean side effects that already occurred are rolled back.
+
+## 5. Internal flow of one model call
+
+```mermaid
+flowchart TD
+    Invoke[invoke: normalize input, select registered transport] --> Initial[Check cancellation and remaining call quota]
+    Initial --> Prepare[Prepare or reuse this transport snapshot]
+    Prepare --> Assemble[Core assembles text, messages, BuiltContext or ContextPlan]
+    Assemble --> Check[Actual message, transport instruction, Schema and optional token budget checks]
+    Check --> Consume[Obtain model call quota, set call deadline]
+    Consume --> Stream[Provider stream: collect chunks and check output budget]
+    Stream --> Finish[Complete response: finish, parse, resolve]
+    Finish --> Deliver[Await content delivery in order, check cancellation]
+    Deliver --> Journal[Commit Journal and completion information]
+    Journal --> Result[Return value and invocation]
+    Stream -.->|cancellation, timeout, upstream or output error| Error[Mark stage and error code and throw]
+    Finish -.->|protocol parsing failure| Error
+```
+
+Core is responsible for generic input assembly and final budget checks and does not implicitly select or compress. When processing is needed, the App registers Support or custom processing nodes into the same Workflow and uses ordinary routes to decide when to execute them. Model calls inside processing nodes share the request quota, cancellation, and deadlines; see [Context nodes](api/context-processing.md) for details.
+
+An ordinary invoke does not require prepare in advance. When early measurement is needed, use `model.prepare(...)` to obtain a single snapshot, call `prepared.measure(input)` repeatedly, then still consume the same handle through `model.invoke({ input, prepared })`. Measurement covers the actual transport instructions and Schema; the final check remains in effect, and the handle is not a quota reservation.
+
+`ModelRunner.sink.output` waits in order for consumers of generated chunks, and the fully parsed value is still returned through invoke; `execution.observe.event` is side-channel observation with isolated failures. Chunk preview and final business delivery are different boundaries.
+
+## 6. Task checks and local repair in the Answering Kit
+
+Corresponds to the seven nodes currently registered by `defineAnswerFlow`; this flow exists only when the Kit is adopted.
+
+```mermaid
+flowchart TD
+    Input[Validate input IDs, item ownership and count] --> Generate[generate: generate only source=ready items]
+    Generate --> Validate[validate: local checks and keep normalized values]
+    Validate --> Review[review: review per off / optional / required policy]
+    Review --> Select[select-repair: select items that are ready and still have issues]
+    Select --> Can{Failed items, repair count and call quota available?}
+    Can -->|yes| Repair[repair: consume one repair chance, submit only failed items and issues]
+    Repair --> Recheck[recheck: re-check only items generated this time]
+    Recheck --> Select
+    Can -->|no| Deliver[deliver: judge item by item]
+    Deliver --> Accepted[accepted: source ready, value present and checks satisfied]
+    Deliver --> Fallback[fallback: App fallback provided a value]
+    Deliver --> Blocked[blocked: no deliverable value]
+```
+
+Initial generation and each repair consume one workflow round; `maxRepairs` additionally limits the number of repairs. `canInvoke` reads the real quota provided by the App, and the Kit does not create an extra model budget. Non-ready sources do not enter generation or repair; items whose review has explicitly failed cannot become passing because review later becomes unavailable. Cancellation, invalid item ownership, and program contract errors throw, and are not automatically disguised as fallback.
+
+## 7. Composition timing of App knowledge answering
+
+The diagram below illustrates an App composition organized by the [Knowledge, Answering, and Presentation contracts](api/knowledge-answering.md); the concrete orchestration and ports are provided by the App. For complete code that can be copied and run directly see [Offline service answering](examples/offline-agent.md); that code does not enable Knowledge/Answering.
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant A as App answer
+    participant T as Answering task catalog
+    participant K as Knowledge / App reader
+    participant F as Answering Flow
+    participant M as Same ModelRunner
+    participant C as App checks and review
+    participant O as Presentation
+    U->>A: question, signal
+    A->>T: Parse task parameters and read
+    T->>K: Call the registered reader
+    K->>K: App authorize, read the fixed revision snapshot
+    K-->>A: Question and source evidence
+    A->>F: Run declared answer items
+    F->>M: generate: call with evidence
+    M-->>F: Draft
+    F->>C: Local checks and policy review
+    C-->>F: Check results and issues
+    loop issues remain and repair count, real quota allow
+        F->>M: Repair only failed items
+        M-->>F: Repaired draft
+        F->>C: Re-check and review
+        C-->>F: Latest check results
+    end
+    F-->>A: accepted / fallback / blocked
+    opt A deliverable value exists
+        A->>O: Bind program source fields and render the template
+        O-->>A: Body text and sources
+    end
+    A-->>U: status, text (if any), issues
+```
+
+If review uses a model, it should consume quota through the same ModelRunner passed in. Fallback evidence and allowed wording are provided by the App; when no deliverable value is provided, blocked is returned. Authorization, reading, cancellation, or contract errors may be thrown directly, with no guarantee of reaching final delivery.

package/development/docs/memory-and-learning.en.md

@@ -0,0 +1,42 @@
+# Memory and continuous accumulation
+
+[Back to development handbook](README.md) · [Shared flow](flows/knowledge-maintenance.md) · [Record templates](records.md)
+
+The library has no out-of-the-box long-term memory database, user profile merging service, or automatic learner of business experience. Core provides execution contracts, Support helps assemble context and calls, and Kits such as Knowledge/Answering provide local processing once adopted. Whether to record, how to assign ownership, and when to update and delete are all explicitly implemented by the App; not recording is also a valid choice.
+
+## Different data needs different rules
+
+| Data | Recommended use | Should not be equated with |
+| --- | --- | --- |
+| Recent Q&A | Session continuity, disambiguation | Tool execution logs, permanent knowledge |
+| Accumulated user preferences | Addressing, expression preferences, ongoing topics | Identity, permissions, public facts |
+| Business experience candidates | Inducing reusable suggestions and failure patterns from results | Proven rules, automatic authorization |
+| Published knowledge | Business facts with explicit sources, scope, and versions | Unverified user self-descriptions |
+| Original materials and extraction results | Current task evidence or authorized archives | Automatically shared knowledge |
+
+Do not use one source-less large summary to hold all categories. Each record category should at least have stable identity, ownership, source, version, status, and retention policy. Template fields are only a starting point; the App defines and validates them, and they are not a new Core protocol that all consumers must follow.
+
+## Application flow for updating user preferences
+
+```text
+Select final Q&A allowed to be recorded, and the watermark
+  → Old summary + new Q&A + explicit merge rules
+  → Model extraction of candidates under budget constraints
+  → Parsing and length/source/sensitive-scope checks
+  → Commit summary and new watermark on the premise of the old version
+  → Subsequent requests read by identity and mark it as low-trust memory
+```
+
+Do not mix the model's internal reasoning, corrections, or unexecuted actions into user profiles. When new expressions conflict with old preferences, apply the App's explicit rules; authoritative human facts are still provided by the corresponding data source. On model failure or version conflict, keep the old summary and the unconsumed watermark and retry with bounds, avoiding lost messages or duplicate merges. Scheduled tasks, storage transactions/CAS, leases, and retries are implemented by the App; the Core per-request budget cannot be assumed to cover background jobs.
+
+## Application flow for experience growth
+
+Register extraction, validation, query, and publication implementations with a fixed task type; adding an experience record is only a data change and does not automatically add a handler. Candidates should be associated with actual sources and results, retain applicability scope, counterexamples, and conflicts, and not treat one success as a universal rule.
+
+Candidate formation → deduplication/conflict checks → business validation or human confirmation → versioned publication → controlled reading, consistent with the [shared flow](flows/knowledge-maintenance.md). To integrate with Knowledge, the App converts permitted records into `KnowledgeDocument`, compiles a new catalog, and switches the request reference; active requests keep using the old snapshot.
+
+`prepare-source.mjs` is used to organize text candidates during development. Runtime persistent learning can reuse its compilation logic and source constraints, while storage, concurrency, and publication policies are provided by the App.
+
+## Decisions required before runtime integration
+
+Record scope and user choices, tenant isolation, visibility scope, retention and deletion, source priority, update conflicts, idempotency keys/consumption watermarks, failure recovery, and which content is forever candidate-only. Without these implementations, documentation and interfaces should state clearly "used for this round/session" or "manually maintained", and must not claim automatic learning.

package/development/docs/operations.en.md

@@ -0,0 +1,51 @@
+# Result delivery, diagnostics, and operations
+
+[Back to development handbook](README.md) · [Core API](api/core.md) · [Support API](api/support.md)
+
+## Boundary of each run
+
+Keep startup manifests separate from per-request state. For each request, establish identity, the allowed knowledge view, an `AbortSignal`, model/tool budget, and source and output state. Credentials, endpoints, model characteristics, and error mapping for connecting to the Provider are managed by the App server, and user materials or model parameters are not allowed to override these configurations.
+
+Consider rounds, model call counts, timeouts, message and output characters, schema size, and business tool quotas separately. Repair, review, and fallback also consume budget; a step called "recovery" cannot mean unlimited retries. Core's model call budget covers only calls that actually pass through that runner; external HTTP, background jobs, and model calls made by the App itself must be limited by the App.
+
+Cancellation must reach the actual model and business I/O; for writes already started, cancellation does not mean rollback. The App should be able to judge whether an operation has executed by idempotency key/real receipt, and query state before retrying. Synchronous ToolRegistry does not wait for arbitrary Promises; asynchronous business logic should be placed in suitable asynchronous handlers/nodes and must not fake synchronous success.
+
+## Verify facts first, then form presentable output
+
+```text
+Parsed model proposal
+  → authorization and real execution
+  → input/output contracts and source checks
+  → generate candidate reply
+  → completeness/business fact checks
+  → program binds sources, action states, and links
+  → deliver in the form chosen by the App
+```
+
+A Knowledge Snapshot is a source reference, a tool event is an execution record, and model text is a candidate explanation; the three do not substitute for each other. Answering's tasks, checks, and bounded repair help organize this chain; the concrete fact checks are provided by the App. See the [knowledge answering API](api/knowledge-answering.md) for the relevant local contracts.
+
+Presentation/Interaction is an optional Kit. InteractionProtocol/CommandCatalog does not determine how the App exchanges data between front end and back end; when used, the App registers commands, parsing, and presentation implementations, and still needs actual receipts from the peer. The App may also directly adopt its own HTTP/SSE/event protocol.
+
+## Error exits
+
+| Actual cause | Program handling | Direction of user-facing wording |
+| --- | --- | --- |
+| Source not provided or not allowed to read | Do not widen permissions, do not generate fake facts | State which kind of available knowledge is missing |
+| Parameters or output violate the contract | Record the specific stage and code; repair or end within budget | State the actual action not completed this time |
+| Provider stream break/timeout | Save known execution state, retry with bounds | Reply incomplete, can retry |
+| Insufficient budget/read limit exceeded | Narrow the legal scope or split the task | State the scope limit; no silent truncation |
+| User cancellation | Stop cancellable work, verify executed operations | State clearly that it stopped and what is confirmed |
+
+Error messages should not show internal schemas, tokens, call protocols, or stack traces verbatim. Logs keep machine-locatable fields, and user copy keeps the accurate cause; not every failure should be described as a connectivity problem.
+
+## What observation and persistence each own
+
+Core's run records/diagnostics and Support's Provider observer provide observation boundaries; they do not automatically create a log database. The App decides whether to output to the console, files, telemetry systems, or a persistent repository, and how to authorize queries, redaction, and retention. `breakWhile` tags are classification hints for interruption, not permission or rule filtering switches; follow the [Support reference](api/support.md).
+
+It is recommended to correlate request/run, stage, model or tool call ID, business error code, knowledge revision/snapshot id, and actual duration. By default do not collect credentials, full prompts, user materials, or model body text; when body-text diagnostics are needed, the product must explicitly enable and limit the scope. Observation callbacks should not change business returns or escalate a record failure into duplicate execution.
+
+## Publication and recovery
+
+Deliver code manifests, knowledge, task references, and configuration as one verifiable version. Validate references before publication and prepare a rollback version; new requests switch to the new catalog while existing requests hold old snapshots. Whether multi-file or database publication is atomic is implemented by the App; the Knowledge in-memory catalog itself provides no storage transactions.
+
+When the App publishes, also state the enabled capabilities, knowledge version, configuration, and changes in externally visible behavior; the new version must still preserve the original permissions, budget, cancellation, and delivery guarantees.

package/development/docs/records.en.md

@@ -0,0 +1,63 @@
+# App data format examples
+
+The JSON below only explains field design for App-owned records; it does not participate in runtime loading, register capabilities, or create data tables. Core does not require this storage format.
+
+Use null/empty arrays to indicate not yet provided, and do not fabricate facts from example default values. Field names, states, and versions are defined and validated by the App itself.
+
+## Material record
+
+Original, extraction status, ownership, lifecycle, and publication status.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": null,
+  "ownerId": null,
+  "scope": "private",
+  "original": { "reference": null, "mediaType": null, "contentSha256": null, "receivedAt": null },
+  "extraction": { "status": "pending", "revision": null, "text": null, "caveats": [] },
+  "lifetime": "turn",
+  "expiresAt": null,
+  "publication": { "status": "unpublished", "documentId": null }
+}
+```
+
+## User preferences
+
+Accumulated interaction preferences, source watermark, and version.
+
+```json
+{
+  "schemaVersion": 1,
+  "ownerId": null,
+  "revision": null,
+  "summary": null,
+  "sourceWindow": { "after": null, "through": null, "references": [] },
+  "updatedAt": null,
+  "expiresAt": null,
+  "status": "uninitialized"
+}
+```
+
+## Experience candidate
+
+Experience source, applicability, validation, and publication status.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": null,
+  "ownerId": null,
+  "revision": null,
+  "status": "candidate",
+  "claim": null,
+  "applicability": [],
+  "sources": [],
+  "counterexamples": [],
+  "conflicts": [],
+  "validation": { "status": "pending", "references": [] },
+  "publication": { "approvedBy": null, "approvedAt": null, "documentId": null }
+}
+```
+
+User preferences cannot carry identity and permissions; experience candidates are not published automatically; raw materials do not automatically enter shared knowledge. See [Knowledge maintenance](maintenance.md), [Materials](materials.md), and [Continuous accumulation](memory-and-learning.md).