docs: two corrections from the convention owner and the spec owner
Both arrived within minutes of the v0.4.0 announcement and both change
what we would otherwise have built or claimed.
CATALOG -- a profile field we must NOT add. Their steg 5 measured bundle
placement across four consumers: exactly one installs a bundle anywhere,
the other three take the bundle directory as a per-run argument with no
default, no discovery and no $HOME expansion. Placement is unmandated, so
BundleProfile gets no root-location or install-path field, "no
installation root" is a conforming consumer shape, and write policy must
not be coupled to placement. Recorded in the split table, which also now
spells the proving consumer's layer prefixes bundle-relative
(concepts/, releases/) rather than repeating the bundle/ prefix their own
repository layout carries -- that prefix was placement leaking into a
contract.
COMMONS -- our "Fixed" framing outruns their frozen text. Removing every
ingest-stamped file is verbatim what ingest-spec v1 section 5 mandates:
v1 assumes one manifest per bundle and defers the multi-manifest case as
a named extension point. So v0.4.0 implements that extension point rather
than fixing a defect against the spec. The mechanic survives ratification
either way -- stem matching follows from their own {stem}@{h} stamp
definition, since {h} changes on every content edit -- but the prose is
queued for amendment and is not ratified, so the changelog now says so
instead of claiming conformance it does not have.
This commit is contained in:
parent
d8e466791c
commit
678f9b2b07
2 changed files with 40 additions and 5 deletions
|
|
@ -120,17 +120,41 @@ Beyond the frontmatter set, `BundleProfile` must carry:
|
|||
escape from strings-only frontmatter.
|
||||
- **Scalar encoding:** the StrictYAML subset (JSON-double-quoted scalars), so
|
||||
a regeneration over the same data is byte-identical.
|
||||
- **Layer/path policy:** `bundle/concepts/` ⇄ layer `concepts`, source_tier
|
||||
`official-docs`, any type except `Release`; `bundle/releases/` ⇄ layer
|
||||
`releases`, source_tier `changelog-derived`, type `Release` exactly.
|
||||
- **Layer/path policy:** `concepts/` ⇄ layer `concepts`, source_tier
|
||||
`official-docs`, any type except `Release`; `releases/` ⇄ layer `releases`,
|
||||
source_tier `changelog-derived`, type `Release` exactly. Their constants
|
||||
spell these `bundle/concepts` and `bundle/releases` because their validator
|
||||
walks a repository whose bundle lives in `bundle/`. That prefix is where
|
||||
*they* keep the bundle, not part of the contract — see "No placement field"
|
||||
below.
|
||||
- **Index policy**, which differs from this library's default in four ways:
|
||||
one index per *directory* rather than one per bundle; entries formatted
|
||||
`* [Title](link) - description` rather than `- [label](target)`; index
|
||||
contents must match the directory exactly, both directions; and the root
|
||||
index carries frontmatter pinning `okf_version`, `bundle_profile`,
|
||||
`okf_spec_commit`.
|
||||
- **Bundle root:** a `bundle/` subdirectory, where this library's default
|
||||
treats the bundle directory as the root itself.
|
||||
## No placement field — a field the profile must NOT grow
|
||||
|
||||
The catalog reported on 2026-07-25 (their commit `3ccb5f6`,
|
||||
`docs/okf-second-brain/spec.md` §1 and §8) that bundle placement is
|
||||
**unmandated**, measured against four consumers rather than taken on report:
|
||||
exactly one installs a bundle anywhere; for the other three the bundle
|
||||
directory is a caller-supplied argument per run, with no default, no discovery
|
||||
and no `$HOME` expansion. Discovery, where it happens, keys on the §3 root
|
||||
marker (`index.md` plus `okf_version`), never on a path.
|
||||
|
||||
Three consequences for `BundleProfile`, recorded here because this phase's
|
||||
non-goal is precisely "do not make the profile too narrow for the Node-world
|
||||
conventions in phase 4":
|
||||
|
||||
- No root-location or install-path field. There is no path form to express.
|
||||
- "No installation root" is a conforming consumer shape, so a profile that
|
||||
assumes every consumer has one would be too narrow in exactly the warned way.
|
||||
- Installing and writing are separate axes: a consumer may write into a bundle
|
||||
it never placed, so write policy must not be tied to a placement concept.
|
||||
|
||||
Every path in this document is therefore bundle-relative, and the bundle
|
||||
directory stays what it is today in both doors — an argument.
|
||||
|
||||
The index-policy divergence is the largest single item. Under the default
|
||||
profile the observable output must stay byte-identical (assumption C1, proven
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue