Publish the portable query and migration specification

00-overview.md

@@ -4,8 +4,9 @@
 
 This specification defines the behavior of tools that treat folders of
 Markdown files as typed, queryable, link-aware data collections. It covers
-collection discovery, JSON Schema types, validation, links, CEL queries, record
-operations, lifecycle policy, and optional runtime workflows.
+collection discovery, JSON Schema types, validation, links, CEL queries,
+ordinary records that save named views, record operations, lifecycle policy,
+and optional runtime workflows.
 
 ## Motivation
 
@@ -44,7 +45,8 @@ workflows.
 
 ## What a conforming tool does
 
-Depending on its conformance profiles, a tool implementing this specification:
+Depending on its conformance profiles and optional features, a tool implementing
+this specification:
 
 1. **Recognizes collections** by the presence of an `mdbase.yaml` configuration
    file.
@@ -56,9 +58,11 @@ Depending on its conformance profiles, a tool implementing this specification:
 5. **Resolves links** between records and exposes link-aware metadata.
 6. **Executes queries** using CEL expressions for filtering, ordering, and
    projection.
-7. **Performs record operations** with validation, reference handling, and
+7. **Executes saved view records** when it advertises the optional
+   `view_records` feature.
+8. **Performs record operations** with validation, reference handling, and
    lifecycle-managed values.
-8. **Loads runtime contracts and workflows** when it supports active behavior.
+9. **Loads runtime contracts and workflows** when it supports active behavior.
 
 Conformance profiles define the expected behavior for each capability and its
 dependencies.
@@ -208,6 +212,14 @@ due_date < today()
 assignee.asFile().team == "engineering"
 ```
 
+### View records save reusable queries
+
+A collection can define the ordinary `view` type and store one or more named
+queries in a Markdown record. Shared query scope, named-view filters,
+projections, ordering, grouping, and summaries remain machine-readable, while
+the Markdown body documents the view for people. Optional presentation metadata
+can select a renderer without changing query results.
+
 ### Validation is progressive
 
 Files in a collection can remain untyped records. Types can be added

01-concepts.md

@@ -82,6 +82,21 @@ lifecycle guards.
 `match.where` uses the standalone structured predicate language defined in
 Chapter 07.
 
+## View
+
+A view is an ordinary Markdown record whose matched type is `view`. It stores
+shared query scope and one or more named queries, with optional advisory
+presentation metadata.
+
+Views do not introduce a second query engine. A view-aware tool resolves a
+named view to the query model from Chapter 11 and executes it through the Query
+profile. Tools that do not support view execution continue to read and validate
+view files as ordinary typed records.
+
+View records are passive collection data. Rendering a view, registering a
+renderer, or connecting user interaction to actions may be tool- or
+runtime-specific, but the record itself is not a runtime contract.
+
 ## Link
 
 A link is a frontmatter value or body reference that can resolve to another

02-collection-layout.md

@@ -37,6 +37,11 @@ collection/
 
 Only `mdbase.yaml` is required. Untyped records form a valid collection.
 
+View records are ordinary records and require no reserved folder. A collection
+MAY organize them under `Views/`, `_views/`, or any other non-excluded path.
+Unlike the configured types folder, such a folder remains part of the normal
+record scan unless explicitly excluded.
+
 ## Reserved Paths
 
 The following paths are reserved by default:

04-configuration.md

@@ -98,6 +98,11 @@ Tools MAY support non-portable UI expression dialects. Portable stored v0.3
 files MUST use the mdbase CEL profile unless a feature declares a different
 extension namespace.
 
+View records use CEL for portable filters, projections, selections, and custom
+summaries. Compatibility tools MAY read another view or expression format, but
+alternate source and round-trip metadata belong under an `x-*` extension and do
+not change the meaning of the portable CEL fields.
+
 ## Version Compatibility
 
 Patch versions within the same stable minor version MUST be backward compatible.

05-type-files.md

@@ -170,6 +170,19 @@ type-file frontmatter against the v0.3 type-file JSON Schema.
 The built-in schema is authoritative during bootstrap. A materialized
 `_types/meta.md` mirrors and documents that behavior.
 
+## View Type
+
+Saved views use the ordinary `view` type defined by
+`schemas/v0.3/view.schema.json`. A collection that stores portable view records
+SHOULD materialize `_types/view.md` with `match.where.type: view` and a local
+reference to that schema. The repository's `_types/view.md` is the canonical
+materialization.
+
+Unlike the meta type, the view type is not required for bootstrap and is not a
+built-in control-file category. A view file remains an ordinary Markdown record
+and participates in normal reads, validation, links, writes, and type matching.
+View-aware execution is the optional behavior defined in Chapter 11.
+
 ## Type Membership
 
 Records may select types explicitly or through inferred matching. Chapter 07

07-collection-semantics.md

@@ -236,6 +236,11 @@ collection:
 Projection values are available to queries. Persistence occurs only through an
 explicit write operation or runtime workflow.
 
+Collection projections enter the effective record and remain available through
+their declared field names. Query- and view-local named projections are
+separate, live under the `projection` CEL namespace, and never replace a
+collection projection or persisted field with the same name.
+
 ## Domain Namespaces
 
 Domain annotations use namespaced extension sections:

10-cel-profile.md

@@ -44,7 +44,8 @@ record fields.
 | Context | Available values |
 | --- | --- |
 | inferred match | candidate raw fields at top level; `record`, `raw`, `present`, `file`, `note` |
-| query or projection | effective fields at top level; `record`, `raw`, `present`, `file`, `note`; `this` for an embedded query |
+| query or projection | effective candidate fields at top level; `record`, `raw`, `present`, `file`, `note`; `projection`; `this` as the invocation-context record or null |
+| query summary | `values`; the fixed operation time and timezone |
 | lifecycle guard | current draft fields at top level; `record`, `raw`, `present`, `old`, `file`, `operation` |
 | workflow variable, trigger, or workflow condition | `event`, `workflow`, `trigger`, `vars` |
 | workflow step condition or input | `event`, `workflow`, `trigger`, `steps`, `vars`; `item` during iteration |
@@ -53,10 +54,10 @@ record fields.
 An unavailable system binding is a compile or preflight diagnostic. For example,
 `steps` is unavailable to a trigger condition because no step has run.
 
-The system names `record`, `raw`, `present`, `file`, `note`, `this`, `old`,
-`operation`, `event`, `workflow`, `trigger`, `steps`, `vars`, and `item` are
-reserved. A frontmatter field with one of those names remains available through
-`record.<field>` and `raw.<field>`.
+The system names `record`, `raw`, `present`, `file`, `note`, `projection`,
+`this`, `values`, `old`, `operation`, `event`, `workflow`, `trigger`, `steps`,
+`vars`, and `item` are reserved. A frontmatter field with one of those names
+remains available through `record.<field>` and `raw.<field>`.
 
 ### Query Context
 
@@ -67,9 +68,32 @@ contains persisted frontmatter. `note` is an alias for `record`.
 present.raw.status == false && record.status == "open"
 ```
 
-`file` supplies the metadata and helpers defined by the collection, query, and
-link profiles. An embedded query may receive `this`, which refers to its
-containing record.
+`file` supplies the candidate metadata and helpers defined by the collection,
+query, and link profiles. `projection` contains named query projections after
+their dependency-ordered evaluation.
+
+`this` is reserved for the query invocation-context record. It is null when no
+context is bound. A non-null context mirrors the candidate query namespaces:
+
+- `this.<field>`, `this.record.<field>`, and `this.note.<field>` expose
+  effective context values
+- `this.raw.<field>` exposes persisted context frontmatter
+- `this.present.record.<field>` and `this.present.raw.<field>` expose presence
+- `this.file` exposes context-file metadata and the helpers available to the
+  active profiles
+
+When an effective context field conflicts with the reserved members `record`,
+`note`, `raw`, `present`, or `file`, it remains available through
+`this.record.<field>` and `this.raw.<field>`.
+
+The host resolves and snapshots the context once before evaluating candidates.
+All candidates see the same immutable context, operation time, and timezone.
+Context link values and `this.file` helpers resolve relative to the context
+record; candidate values and `file` helpers resolve relative to the candidate.
+`this` is record-only and MUST NOT be repurposed as an arbitrary caller
+parameter map. A feature that adds parameters uses a distinct binding and
+declares its own context contract.
+Chapter 11 defines portable context binding and saved-view invocation.
 
 ### Matching Context