Complete memory graph and document value workplans

docs/api-reference.md

@@ -7,9 +7,11 @@ Generated from `markitect_tool.__all__`.
 - `BACKEND_CAPABILITIES` - object. set() -> new empty set object
 - `DEFAULT_BACKEND_PATHS` - object. Built-in immutable sequence.
 - `DEFAULT_LOCAL_INDEX_PATH` - object. str(object='') -> str
+- `DOCUMENT_VALUE_KINDS` - object. set() -> new empty set object
 - `EMPTY_PARSE_OPTIONS_HASH` - object. str(object='') -> str
 - `EXPLODE_MANIFEST_NAME` - object. str(object='') -> str
 - `LOCAL_INDEX_SCHEMA_VERSION` - object. str(object='') -> str
+- `MAX_FUNCTION_PIPELINE_DEPTH` - object. int([x]) -> integer
 - `NORMALIZED_SOURCE_SCHEMA_VERSION` - object. str(object='') -> str
 - `SOURCE_ADAPTER_ENTRY_POINT_GROUP` - object. str(object='') -> str
 
@@ -122,8 +124,12 @@ Generated from `markitect_tool.__all__`.
 - `DocumentFunctionEvaluationResult(content: 'str', calls: 'list[DocumentFunctionRun]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>) -> None` - class. Result of expanding document functions in a Markdown document.
 - `DocumentFunctionParameter(name: 'str', kind: 'str' = 'string', required: 'bool' = True, default: 'Any' = None, variadic: 'bool' = False, description: 'str | None' = None) -> None` - class. One declared document function parameter.
 - `DocumentFunctionRegistry(descriptors: 'list[DocumentFunctionDescriptor] | None' = None) -> 'None'` - class. Registry and evaluator for document functions.
-- `DocumentFunctionRun(call: 'DocumentFunctionCall', output: 'Any' = None, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>) -> None` - class. One function call result.
+- `DocumentFunctionRun(call: 'DocumentFunctionCall', output: 'Any' = None, value: 'DocumentValue | None' = None, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>) -> None` - class. One function call result.
+- `DocumentValue(kind: 'str', value: 'Any' = None, items: "list['DocumentValue']" = <factory>, fields: "dict[str, 'DocumentValue']" = <factory>, metadata: 'dict[str, Any]' = <factory>, provenance: 'list[dict[str, Any]]' = <factory>) -> None` - class. Typed value produced by a document function.
+- `coerce_document_value(value: 'Any', *, declared_kind: 'str' = 'dynamic') -> 'DocumentValue'` - function. Coerce a Python value into a typed document value.
 - `default_document_function_registry() -> 'DocumentFunctionRegistry'` - function. Return built-in deterministic document functions.
+- `document_value_to_json(value: 'DocumentValue | Any') -> 'dict[str, Any]'` - function. Return the stable JSON-compatible representation of a document value.
+- `format_document_value(value: 'DocumentValue | Any', *, inline: 'bool') -> 'str'` - function. Map a typed document value to deterministic Markdown text.
 - `parse_document_function_calls(text: 'str') -> 'list[DocumentFunctionCall]'` - function. Parse inline and fenced document function calls.
 - `render_document_functions(text: 'str', *, registry: 'DocumentFunctionRegistry | None' = None, context: 'ProcessingContext | None' = None) -> 'DocumentFunctionEvaluationResult'` - function. Expand deterministic document functions in Markdown content.
 - `validate_document_functions(text: 'str', *, registry: 'DocumentFunctionRegistry | None' = None, allowed: 'list[str] | None' = None, forbidden: 'list[str] | None' = None) -> 'DocumentFunctionEvaluationResult'` - function. Validate function calls without rendering the document.

docs/document-functions.md

@@ -78,6 +78,38 @@ Initial deterministic functions:
 | `md.codeblock` | Create a fenced code block. |
 | `data.get` | Read a value from processing context variables. |
 
+## Typed Values
+
+Document functions now expose typed result values in addition to their legacy
+raw `output` field. Each `DocumentFunctionRun` includes a `value` object with a
+stable `kind`, metadata, and optional provenance.
+
+Supported value kinds:
+
+| Kind | Markdown mapping |
+| --- | --- |
+| `string` | Inline or block text. |
+| `number` | Decimal text. |
+| `boolean` | `true` or `false`. |
+| `none` | Empty text. |
+| `markdown` | Markdown content passed through directly. |
+| `list` | Comma-separated inline text or newline-separated block text. |
+| `dictionary` | Stable JSON object text. |
+| `record` | Stable JSON object text. |
+| `table` | Deterministic Markdown table. |
+| `reference` | Label/title/value text, with provenance required. |
+| `content_unit` | Label/title/value text, with provenance required. |
+| `unknown` | Diagnostic fallback for mismatched output values. |
+| `dynamic` | Reserved for explicitly dynamic values. |
+
+Function descriptors declare `output_type`; execution validates the returned
+value against that declaration. Mismatches produce
+`function.output_type_mismatch`, while reference-like values without provenance
+produce `function.provenance_missing`.
+
+The raw `output` field remains for compatibility. New callers should prefer
+`value` for typed API use and use the mapper when Markdown output is needed.
+
 ## CLI
 
 List functions:
@@ -132,18 +164,44 @@ capabilities before execution. External policy services may provide decisions
 through adapters later, but deterministic function execution has no external
 service dependency.
 
+## Syntax Boundary
+
+The supported syntax remains intentionally conservative:
+
+- inline calls with `{{mkt:...}}`
+- fenced calls with `mkt-function`
+- positional and named arguments parsed with shell-like quoting
+- pipeline chaining with quoted pipe characters preserved
+- `${name}` context variable lookup
+- bounded pipeline depth to avoid accidental runaway expressions
+
+Deferred syntax:
+
+- nested function expressions
+- document-local function definitions
+- conditionals, loops, lambdas, or general scripting
+- Quarkdown syntax compatibility in the core parser
+
 ## Natural Extensions
 
 The deterministic layer deliberately stops before becoming a full publishing
-language. Future extension work is captured in
-`MKTT-WP-0015: Render And Document Function Extensions`.
+language. The original broad render/function follow-up has been split into
+native workplans:
 
-That workplan should consider:
+- `MKTT-WP-0015`: typed document-function value contracts.
+- `MKTT-WP-0020`: render/export adapter contracts.
+- `MKTT-WP-0021`: render reference and asset manifest contracts.
+- `MQD-WP-0001`: concrete Quarkdown adapter implementation in
+  `markitect-quarkdown`.
+- `MKTF-WP-0003`: read-side source attachment metadata compatibility in
+  `markitect-filter`.
+
+Those workplans should consider:
 
 - typed document values and value-to-Markdown mapping
-- richer multiline and nested function syntax
-- document-local reusable functions
-- render/export adapters, including optional Quarkdown source export
+- constrained parser compatibility improvements, while deferring nested
+  function expressions and document-local reusable functions
+- render/export adapter contracts, including optional Quarkdown source export
 - render-aware numbering, references, tables, figures, equations, and code
   blocks
 - static asset and media manifests with checksums

docs/examples-index.md

@@ -18,7 +18,7 @@ This index maps example files to practical usecases and useful commands.
 | `examples/references/context.md` | Namespace, region, fence, and section references | `mkt ref resolve examples/references/context.md 'std:clauses.md#payment-terms' --root examples/references` |
 | `examples/references/standard/clauses.md` | Referenced reusable content | Use with `mkt ref resolve` or `mkt process` |
 | `examples/migration/legacy-path-include.md` | Migration-style include handling | `mkt include examples/migration/legacy-path-include.md --base-dir examples/migration` |
-| `examples/functions/basic-functions.md` | Deterministic document functions | `mkt function render examples/functions/basic-functions.md` |
+| `examples/functions/basic-functions.md`, `examples/functions/typed-values.md` | Deterministic document functions and typed value examples | `mkt function render examples/functions/basic-functions.md` |
 
 ## Templates, Generation, And Workflows
 
@@ -46,7 +46,8 @@ This index maps example files to practical usecases and useful commands.
 | `examples/policy/local-label-policy.yaml` | Local policy gateway | `mkt policy check public-agent read note --policy examples/policy/local-label-policy.yaml --label public` |
 | `examples/policy/enterprise-policy-map.yaml` | Enterprise IAM mapping fixture | `mkt policy subject examples/policy/netkingdom-claims.yaml --policy-map examples/policy/enterprise-policy-map.yaml` |
 | `examples/memory/workplan-context.manifest.yaml` | Context package manifest | `mkt context pack examples/memory/workplan-context.manifest.yaml --root . --no-save` |
-| `examples/memory/memory-profile.local.yaml`, `examples/memory/decision-graph*.yaml` | Memory graph/profile contract fixtures | `mkt memory graph pack examples/memory/decision-graph-selection.yaml --format yaml` |
+| `examples/memory/memory-profile.local.yaml`, `examples/memory/*graph*.yaml`, `examples/memory/*path*.yaml`, `examples/memory/*neighborhood*.yaml` | Memory graph/profile contract fixtures | `mkt memory graph pack examples/memory/decision-graph-selection.yaml --format yaml` |
+| `examples/memory/invalid-memory-*.yaml`, `examples/memory/runtime-adapter-boundaries.yaml` | Negative memory fixtures and runtime handoff descriptors | `mkt memory graph validate examples/memory/invalid-memory-graph.yaml --format text` |
 
 ## Literate And Migration
 

docs/memory-graph-contract.md

@@ -42,10 +42,10 @@ validation so that cross-repository contracts do not drift silently.
 
 Valid node kinds include `question`, `claim`, `assumption`, `evidence`,
 `decision`, `alternative`, `outcome`, `risk`, `follow_up`, `turn`, `plan`,
-`tool_call`, `observation`, `edit`, `validation`, `task`, `topic`, `document`,
-`entity`, `artifact`, `concept`, `capability`, `contract`, `policy`,
-`preference`, `source_fact`, `episode`, `finding`, `constraint`, `profile`,
-`context_package`, and `memory`.
+`tool_call`, `observation`, `edit`, `validation`, `interruption`,
+`activation`, `task`, `topic`, `document`, `entity`, `artifact`, `concept`,
+`capability`, `contract`, `policy`, `preference`, `source_fact`, `episode`,
+`finding`, `constraint`, `profile`, `context_package`, and `memory`.
 
 Valid edge kinds include `supports`, `contradicts`, `depends_on`,
 `derived_from`, `led_to`, `affects`, `references`, `relates_to`, `supersedes`,
@@ -70,6 +70,42 @@ mkt memory graph validate examples/memory/decision-graph.yaml
 mkt memory graph pack examples/memory/decision-graph-selection.yaml --format yaml
 ```
 
+## Fixture Catalog
+
+The memory fixtures cover the three intended memory views:
+
+| Files | View | Purpose |
+| --- | --- | --- |
+| `examples/memory/decision-graph.yaml`, `examples/memory/decision-graph-selection.yaml` | reasoning | Decision and constraint path that pins the contract/runtime boundary. |
+| `examples/memory/conversation-path.yaml`, `examples/memory/conversation-path-selection.yaml` | conversation | Short-term branch/plan/tool/observation episode with event activation. |
+| `examples/memory/knowledge-neighborhood.yaml`, `examples/memory/knowledge-neighborhood-selection.yaml` | knowledge | Durable neighborhood around schema versions, docs, compiler capability, and runtime policy. |
+| `examples/memory/memory-profile.local.yaml` | mixed profile | Local profile declaring reasoning, knowledge, and package stores plus activation limits. |
+| `examples/memory/invalid-memory-graph.yaml`, `examples/memory/invalid-memory-profile.yaml` | invalid | Negative fixtures for validation diagnostics and handoff contract tests. |
+
+The valid selections compile to standard `ContextPackage` output. Invalid
+fixtures are deliberately small so downstream runtimes can assert diagnostic
+codes without needing Markitect-owned durable storage.
+
+## Runtime Adapter Handoff
+
+`examples/memory/runtime-adapter-boundaries.yaml` is a non-executing descriptor
+catalog for external memory runtimes and stores. It names the contracts that
+runtime packages should accept or emit while keeping Markitect limited to local
+validation, planning, and package compilation.
+
+The descriptor catalog covers:
+
+| Boundary | Responsibility |
+| --- | --- |
+| `memory.runtime.kontextual-engine` | Durable graph snapshots, event append, selection resolution, and refresh execution. |
+| `memory.runtime.phased-memory` | Future lifecycle policies such as compaction, retention intent, and observability. |
+| `memory.store.external-graph` | External graph database path and neighborhood queries. |
+| `memory.store.vector` | Embedding and vector retrieval flows that return graph selections. |
+| `memory.extract.llm-assisted` | Optional graph extraction proposals from transcripts or source artifacts. |
+| `memory.policy.enterprise-pdp` | Runtime policy authorization and activation reauthorization. |
+| `memory.registry.remote` | Future remote profile/package registry interactions. |
+| `memory.audit.sink` | Durable audit and policy decision event sinks. |
+
 This keeps Markitect as the compiler/contract boundary. `kontextual-engine`
 should implement runtime stores and event production against these schemas, and
 `infospace-bench` should benchmark generated context packages and runtime

docs/workplan-planning-map.md

@@ -138,6 +138,16 @@ extension descriptors, `mkt source` commands, API exports, fake adapter
 fixtures, and sibling-repo migration notes. Concrete EPUB3 extraction remains
 `markitect-filter` scope.
 
+`MKTT-WP-0015` has been narrowed to document-function typed value contracts.
+The former render-and-function extension scope is split across native
+workplans: `MKTT-WP-0020` owns render/export adapter contracts,
+`MKTT-WP-0021` owns passive render reference and asset manifests,
+`MQD-WP-0001` owns concrete Quarkdown adapter implementation in
+`markitect-quarkdown`, and `MKTF-WP-0003` owns read-side source attachment
+metadata compatibility in `markitect-filter`. This preserves the
+`markitect-filter` read-only boundary and avoids pulling renderer execution
+into `markitect-tool`.
+
 ## State Hub Mirror
 
 Native State Hub dependency edges should mirror the whole-workstream
@@ -182,3 +192,8 @@ dependencies:
 - `MKTT-WP-0018 -> MKTT-WP-0013`
 - `MKTT-WP-0018 -> MKTT-WP-0017`
 - `MKTT-WP-0018 -> MKTT-WP-0019`
+- `MKTT-WP-0020 -> MKTT-WP-0013`
+- `MKTT-WP-0020 -> MKTT-WP-0015`
+- `MKTT-WP-0021 -> MKTT-WP-0010`
+- `MKTT-WP-0021 -> MKTT-WP-0015`
+- `MKTT-WP-0021 -> MKTT-WP-0020`