Intentset Publication Profile v0.2

Draft intentset/publication/0.2 · revision 2026-10-14 · implemented by 0.10.0 · Rendered from spec/publication.md in the repository.

Extends: Core §9, and follows Core §1's change policy.

Publication turns reviewed knowledge, the explanations a product's readers are given, into documentation and in-app help for one audience and release, and leaves out everything that audience may not see. It is not deployment: nothing here ships a product. Core §9 names the generated publication profile and lists the provenance a published knowledge document must retain. This note fixes the fields that carry it, the review record that decides needs-review, and the diagnostics a publisher reports. MUST, MUST NOT, SHOULD and MAY are used as in Core §1.

1. Request and projection

A publication request names visibility, audience, product, release, role, edition and flags, and MAY name ids (knowledge IDs; omitted means every eligible one). Every other field is required: a missing one MUST refuse the request rather than be read as "any", and flags: [] is the only way to say "no flags". Each value MUST be one the registries declare (the product: a product artifact in the snapshot); an unknown value, such as an unknown release label, MUST refuse the request rather than match nothing.

A knowledge artifact is eligible only when all hold: type knowledge; status approved, implemented, released or deprecated; visibility admitted; the request's audience in audiences; availability present; the request's product, release, role and edition each in the corresponding list; every flag in availability.flags named by the request; and its review current (§3). Everything else is excluded. An excluded artifact the request named in ids is CORE008. When the artifact's visibility is outside the projection, or no artifact has the ID, the diagnostic MUST be the same in both cases and MUST NOT carry a path.

2. The generated document

A generated document is UTF-8 Markset. Its frontmatter holds markset: 0 and one top-level key, intentset-publication; it MUST NOT hold an intentset key, so it is never read as a canonical record. The line after the frontmatter MUST be <!-- Generated by intentset publish from <ID>; do not edit. -->. The body MUST be the knowledge body unchanged, preceded by one blank line when it does not begin with one. The published path is <ID>.md.

Fields appear in this order. Strings are plain only when they cannot be read as another type, and are otherwise single-quoted; sequences are indented under their key. An HTML rendering SHOULD carry the same block, as canonical JSON, in <meta name="intentset-publication">. The document MUST parse as Markset version 0 without errors and MUST NOT contain a ::: directive outside Markset's vocabulary. Retrieval chunks of a document MUST carry its intentset-publication block unchanged.

3. Review record and needs-review

A review is reviewedBy and reviewedAt on the knowledge plus this extension, which pins the source hash each source had when the knowledge was reviewed:

extensions:
  intentset.org/review:
    sources:
      BEH-ASMT-SCHEDULE: 2f533532d2e5...   # SHA-256 of the source file, ADR 0005
      RULE-ASMT-FUTURE: e39f8756c878...
    snapshot: <commit or graph hash at review>   # optional, informative

The sources a review MUST pin are those the knowledge explains and the rules in governedBy of each explained behavior. The knowledge is needs-review, and MUST NOT be published, when any such source's current hash differs from its pin or the source is gone, when a pin is missing, or when reviewedBy or reviewedAt is absent.

In conformance fixtures only, a pin of the literal @current stands for the source's hash in the case's own tree and is bound before projection. Unbound, it equals no hash and so reads as changed.

4. References and diagnostics

A body MUST NOT refer, by bare ID, to an artifact whose visibility the projection does not admit, other than the requested product; nor link to, or write out the repository path of, an artifact not published in the same run. A document refused here refuses, in turn, any document that links to it. A body MUST NOT contain, case-sensitively and with any whitespace between words, the title (three or more words) of an artifact the projection does not admit, unless a published artifact has the same title. No publication diagnostic may contain the title or path of an artifact the projection does not admit; it names such an artifact by ID only.

Every publication diagnostic has origin publication and severity error. An exclusion is reported, for counting, as one of not-requested, not-knowledge, draft, retired, visibility, audience, availability-missing, product, release, role, edition, flag, needs-review (the first that applies, in that order), or, for an eligible document refused later, reference, title, directive, markset. The index counts an exclusion only when the projection admits the excluded artifact's visibility, so a public or customer index never reveals how many internal or restricted records exist; a refused request counts nothing.

5. The help file

Beside the documents, a publication writes help.json: every tip (Core §9) of every document published in the run, keyed by the ID it explains, for a product's runtime to show beside the control that delivers that behavior. It is one UTF-8 JSON object with its keys sorted, written whenever the request is accepted, so a runtime can rely on it being there, and the same bytes for the same inputs.

A tip is written exactly when its knowledge was published in the same run, so what gates a tip is what gates its document: status, visibility, audience, availability and review. The key is the explained artifact's ID whatever that artifact's visibility, because a product that binds a control to the ID has already written it where the same reader can see it, and the file carries nothing else of that artifact: never its title, path, status or prose. When two published documents tip the same ID, the tip from the knowledge with the lower ID is written. A retrieval system MUST NOT index the help file as knowledge; its text is already in the documents it points at.