okf 1.12.0 → 2.0.0

data/lib/okf/markdown/links.rb

@@ -4,7 +4,7 @@ module OKF
   module Markdown
     # Markdown cross-link extraction and resolution — the single source of truth for
     # "which concepts does this body point at". Shared by OKF::Bundle::Graph (to build edges)
-    # and OKF::Bundle::Validator (to warn on broken cross-links, §5.3), so both agree on what
+    # and OKF::Bundle::Validator (to warn on broken cross-links, §6.1), so both agree on what
     # counts as a link and where it resolves.
     module Links
       FENCE = /\A(```|~~~)/.freeze
@@ -14,13 +14,34 @@ module OKF
       # blanked before scanning — the inline analogue of FENCE.
       CODE_SPAN = /(`+).*?\1/.freeze
       # Inline link [text](target) or [text](target "title"); (?<!!) skips images.
-      INLINE_LINK = /(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/.freeze
+      # group 1 = the link text, group 2 = the target: extract() wants only the
+      # target, Citations.entries carries the text into a source's `title` —
+      # one grammar, one regex.
+      INLINE_LINK = /(?<!!)\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/.freeze
       # Reference-style use: full [text][label] or collapsed [label][]; (?<!!) skips
       # images. group 1 = text/label, group 2 = the explicit label (empty if collapsed).
       REFERENCE_LINK = /(?<!!)\[([^\]]*)\]\[([^\]]*)\]/.freeze
       # Reference definition: [label]: target  (optionally followed by a "title").
-      DEFINITION = /\A[ \t]{0,3}\[([^\]]+)\]:[ \t]*(\S+)/.freeze
-      SCHEME = %r{\A[a-z][a-z0-9+.-]*://}.freeze
+      # A label may not begin with `^`: that is a footnote definition (§5.1
+      # per-claim attribution), which would otherwise read as a reference
+      # definition nothing ever uses.
+      DEFINITION = /\A[ \t]{0,3}\[([^\^\]][^\]]*)\]:[ \t]*(\S+)/.freeze
+      # In-prose footnote reference [^label] — §5.1 joins it on a sources[].id;
+      # (?<!!) skips an image whose alt text happens to start with a caret.
+      FOOTNOTE_REFERENCE = /(?<!!)\[\^([^\]\s]+)\]/.freeze
+      # A footnote definition line ([^label]: prose) — never a reference.
+      FOOTNOTE_DEFINITION = /\A[ \t]{0,3}\[\^([^\]\s]+)\]:/.freeze
+      # The URI scheme grammar, in one source string the citation item
+      # regexes compose from — schemes are case-insensitive (RFC 3986), and
+      # answering the case question in two places had HTTP:// counted as
+      # provenance by Citations and as prose by this module.
+      SCHEME_NAME = "[a-zA-Z][a-zA-Z0-9+.-]*"
+      SCHEME = %r{\A#{SCHEME_NAME}://}.freeze
+      # mailto has no ://, so SCHEME cannot see it — and a scheme name is as
+      # case-insensitive here as everywhere else. This guard sat inline and
+      # case-sensitive in three places; `MAILTO:user@example.md` then passed
+      # both gates and resolved as a relative path.
+      MAILTO = /\Amailto:/i.freeze
 
       module_function
 
@@ -33,7 +54,7 @@ module OKF
         definitions = reference_definitions(text)
         found = []
         each_prose_line(text) do |line|
-          found.concat(line.scan(INLINE_LINK).flatten)
+          line.scan(INLINE_LINK) { |_text, target| found << target }
           line.scan(REFERENCE_LINK).each do |label, explicit|
             key = (explicit.empty? ? label : explicit).strip.downcase
             target = definitions[key]
@@ -55,6 +76,34 @@ module OKF
         definitions
       end
 
+      # The distinct footnote labels referenced in prose (§5.1), in document
+      # order. A definition's own leading token is not a reference — a source
+      # cited only by `[^a]:` itself is still uncited — but the prose *after*
+      # it is prose like any other: `[^a]: see also [^b]` cites b, and skipping
+      # the whole line made that citation invisible to both provenance checks.
+      # Labels are deduplicated so one unmatched label yields one finding, not
+      # one per use.
+      def footnote_references(text)
+        labels = []
+        each_prose_line(text) do |line|
+          line.sub(FOOTNOTE_DEFINITION, "").scan(FOOTNOTE_REFERENCE) { |captures| labels << captures.first }
+        end
+        labels.uniq
+      end
+
+      # The footnote labels a body *defines* (`[^label]: …`), deduplicated. A
+      # label with a definition is a self-contained GFM content footnote;
+      # §5.1's keyed attribution never reserves the whole label space, so the
+      # provenance checks treat only undefined, unmatched labels as dangling.
+      def footnote_definitions(text)
+        labels = []
+        each_prose_line(text) do |line|
+          match = FOOTNOTE_DEFINITION.match(line)
+          labels << match[1] if match
+        end
+        labels.uniq
+      end
+
       # Yield each line outside a fenced code block, with inline code spans blanked.
       # Both exclusions mirror the rendered document: fenced and inline code are
       # literal text, so a link written inside them is not a cross-link.
@@ -79,9 +128,20 @@ module OKF
       # @param bundle [String] path to the bundle root
       def resolve(raw, from:, bundle:)
         target = raw.to_s.split("#", 2).first.to_s
-        return nil if target.empty? || target.end_with?("/")
-        return nil if target.match?(SCHEME) || target.start_with?("mailto:")
         return nil unless target.end_with?(".md")
+
+        resolve_path(raw, from: from, bundle: bundle)
+      end
+
+      # The path arithmetic under #resolve without its +.md+ gate — the resolver
+      # for §6.2's path-valued frontmatter fields (resource, sources[].resource,
+      # computation, executor.resource, attester.resource), which accept any
+      # file. Body cross-links stay .md-only through #resolve; keeping the gate
+      # there and not here is what stops the two rules from trading places.
+      def resolve_path(raw, from:, bundle:)
+        target = raw.to_s.split("#", 2).first.to_s
+        return nil if target.empty? || target.end_with?("/")
+        return nil if target.match?(SCHEME) || target.match?(MAILTO)
         return target.sub(%r{\A/+}, "") if target.start_with?("/")
 
         bundle_abs = File.expand_path(bundle)

data/lib/okf/path.rb

@@ -24,11 +24,25 @@ module OKF
       relative = normalize_relative!(path)
       expanded_root = File.expand_path(root.to_s)
       expanded_path = File.expand_path(File.join(expanded_root, relative))
-      unless expanded_path == expanded_root || expanded_path.start_with?("#{expanded_root}#{File::SEPARATOR}")
-        raise Error, "path escapes bundle root"
-      end
+      raise Error, "path escapes bundle root" unless under?(expanded_root, expanded_path)
 
       expanded_path
     end
+
+    # Is +path+ the root itself or a descendant of it? Pure string containment
+    # (no disk access), so it works on both lexical paths (File.expand_path) and
+    # symlink-resolved ones (File.realpath) — the shell resolves, this decides.
+    # Both arguments must already be absolute and normalized the same way.
+    #
+    # The prefix guards against a sibling passing as a child ("/foo" is not under
+    # "/food"), and reuses the root itself as the prefix when the root already
+    # ends in the separator — i.e. the filesystem root "/", whose children would
+    # otherwise be tested against "//" and every one rejected.
+    def self.under?(root, path)
+      return true if path == root
+
+      prefix = root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+      path.start_with?(prefix)
+    end
   end
 end

data/lib/okf/render/graph/template.html.erb

@@ -8,7 +8,7 @@
 <meta property="og:site_name" content="OKF">
 <meta property="og:title" content="<%= og_title %>">
 <meta property="og:description" content="<%= og_desc %>">
-<meta property="og:image" content="https://okfgem.com/og-demo-v3.png">
+<meta property="og:image" content="https://okfgem.com/og-demo-v5.png">
 <meta property="og:image:type" content="image/png">
 <meta property="og:image:width" content="1200">
 <meta property="og:image:height" content="630">
@@ -16,7 +16,7 @@
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="<%= og_title %>">
 <meta name="twitter:description" content="<%= og_desc %>">
-<meta name="twitter:image" content="https://okfgem.com/og-demo-v3.png">
+<meta name="twitter:image" content="https://okfgem.com/og-demo-v5.png">
 <meta name="twitter:image:alt" content="An interactive Open Knowledge Format knowledge graph.">
 <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='24' fill='%231a1a1a'/><polygon points='38,44 62,44 50,82' fill='%237a0a1e'/><polygon points='18,44 38,44 50,82' fill='%23a8112c'/><polygon points='62,44 82,44 50,82' fill='%23a8112c'/><polygon points='35,28 18,44 38,44' fill='%23dc1e3c'/><polygon points='65,28 82,44 62,44' fill='%23dc1e3c'/><polygon points='35,28 65,28 62,44 38,44' fill='%23f43f5e'/><polygon points='36,29 49,29 42,42' fill='%23fff' opacity='.38'/><polygon points='35,28 65,28 82,44 50,82 18,44' fill='none' stroke='%23ff6b7f' stroke-width='2' stroke-linejoin='round'/></svg>">
 <script>/* Resolve theme before first paint so there is no flash. */
@@ -246,7 +246,31 @@
   background:var(--line-2);border:1px solid var(--line);border-radius:7px;padding:3px 9px}
  .badge .dot{width:8px;height:8px;border-radius:50%}
  .status{font-size:10.5px;font-weight:600;text-transform:uppercase;letter-spacing:.04em;padding:2px 7px;border-radius:5px;color:var(--muted);background:var(--line-2)}
+ /* §5.4's three, plus `shipped` — which this project used before the spec named
+    a vocabulary, and which stays styled because §4.1 lets a producer use any
+    value and requires a consumer to tolerate it. `stable` gets no rule because
+    it is never rendered: an absent status defaults to it, so badging it would
+    put a meaningless chip on every concept of every bundle. */
+ .status.draft{color:var(--warn);background:color-mix(in srgb,var(--warn) 14%,transparent)}
+ .status.deprecated{color:var(--accent-ink);background:color-mix(in srgb,var(--accent) 12%,transparent)}
  .status.shipped{color:var(--ok);background:color-mix(in srgb,var(--ok) 14%,transparent)}
+ /* §5.3's trust tiers — the third visual channel, after type colour and status.
+    Deliberately quieter than status: how much to believe a concept is a question
+    a reader asks *of* the card, where a deprecation is the card shouting. */
+ .tier{font-size:10.5px;font-weight:600;letter-spacing:.02em;padding:2px 7px;border-radius:5px;
+  color:var(--muted);background:var(--line-2);border:1px solid var(--line)}
+ .tier.machine-confirmed{color:var(--accent-ink);background:color-mix(in srgb,var(--accent) 12%,transparent);border-color:transparent}
+ .tier.human-reviewed{color:var(--ok);background:color-mix(in srgb,var(--ok) 14%,transparent);border-color:transparent}
+ /* Past the expiry its own author declared (§5.5), judged against the viewer's
+    clock. Warn-coloured wherever it appears — a card's meta row, the trust line. */
+ .stale{color:var(--warn)}
+ /* The inspector's trust line: the chips under a concept's description. */
+ .meta-trust{display:flex;flex-wrap:wrap;gap:6px;align-items:center;margin-top:8px}
+ /* The two text members of the line, as opposed to the .tier/.status badges
+    that carry their own size. `.stale` has only a colour globally, so
+    without this it rendered at the panel's inherited size beside them. */
+ .meta-trust .gen,.meta-trust .stale{font-size:11.5px}
+ .meta-trust .gen{color:var(--faint)}
  .tag{background:var(--line-2);border:1px solid var(--line);border-radius:6px;padding:2px 8px;font-size:11px;color:var(--muted)}
 
  /* ── graph view ── */
@@ -1034,6 +1058,12 @@
       <div class="fgroup"><h4>Types</h4><div class="fchips" id="cat-ftypes"></div></div>
       <div class="fgroup"><h4>Dirs</h4><div class="fchips" id="cat-fdirs"></div></div>
       <div class="fgroup"><h4>Tags</h4><div class="fchips" id="cat-ftags"></div></div>
+      <!-- §5.3/§5.4. Counted off the catalog rather than a fixed vocabulary,
+           and hidden entirely when the bundle says nothing about either — a
+           v0.1 bundle's whole trust posture is not worth a row of chips
+           reading "unverified 9". -->
+      <div class="fgroup" id="cat-fstatus-group" hidden><h4>Status</h4><div class="fchips" id="cat-fstatus"></div></div>
+      <div class="fgroup" id="cat-ftrust-group" hidden><h4>Trust</h4><div class="fchips" id="cat-ftrust"></div></div>
      </div>
     </aside>
    </section>
@@ -1170,7 +1200,7 @@
      view switching                full-text search
      catalog                       files
      tags                          stats
-     theme / fullscreen            §6 map payload · §7 log payload
+     theme / fullscreen            §8 map payload · §9 log payload
      command palette               the search bridge
      concept preview (touch)       mobile drawer + sheet
      keyboard                      deep links · first visit
@@ -1224,18 +1254,22 @@ const SEARCH_ENDPOINT=<%= search_endpoint_json %>;
    cannot use — and the panel reads that null to explain itself. */
 const MANAGE_ROOT=<%= manage_root_json %>, MANAGE_TOKEN=<%= manage_token_json %>;
 /* null when served live (`okf server`) — the getters below fetch the endpoints
-   above. `okf render` injects a payload {catalog,index,logs,bodies}, and every
-   getter resolves from it instead (the /node/meta fragment derived from the
-   catalog), so one file needs no server and the endpoint consts above go inert. */
+   above. `okf render` injects a payload {catalog,index,logs,bodies,sources}, and every
+   getter resolves from it instead (the /node/meta trust line composed from the
+   catalog row), so one file needs no server and the endpoint consts above go inert. */
 const EMBED=<%= embed_json %>;
 /* Full-text search state (MiniSearch, lazy — built on first search). One ranked
    index behind the search box for the graph, catalog and files views. It indexes
-   title/id/type/tags/description in every mode, plus each concept body wherever
-   the page already holds it: `okf render` bakes every body in, so a static file
-   searches bodies offline; the live server keeps bodies lazy, so its index stays
-   metadata-only until a backend body index arrives. Same 7.2.0 build and config
-   as the Ruby port, so a Ruby-built index and this one rank identically. */
-const FT_FIELDS=['title','id','type','tags','description'].concat(EMBED?['body']:[]);
+   title/id/type/tags/description in every mode, plus each concept body and its
+   source text wherever the page already holds them: `okf render` bakes both in,
+   so a static file searches them offline; the live server keeps bodies lazy and
+   carries only a source *count* on a catalog row, so its index stays
+   metadata-only until a backend body index arrives. The asymmetry is
+   pre-existing and deliberate — spending body-sized bytes on every /catalog
+   fetch to serve one view is the trade the payload already refuses for `body`
+   (see .okf/capabilities/search.md). Same 7.2.0 build and config as the Ruby
+   port, so a Ruby-built index and this one rank identically. */
+const FT_FIELDS=['title','id','type','tags','description'].concat(EMBED?['body','sources']:[]);
 let _MiniSearch=null,ftIndex=null,ftBuilding=null;
 const descOf={};
 const MIN=<%= OKF::Render::Graph::MIN_SIZE %>, MAX=<%= OKF::Render::Graph::MAX_SIZE %>;
@@ -1522,7 +1556,7 @@ interceptMdLinks(sideBody,()=>shownId,select,r=>r.kind==='index'?showDir(r.dir):
 interceptMdLinks(document.getElementById('fp-body'),()=>fileSel,id=>openFile(id),
  r=>openReserved(r.kind,r.kind==='index'?ixPathOf(r.dir):r.path));
 /* Clicking a folder node (tree mode) or an area box (cluster mode) opens that
-   directory's §6 index entry in the inspector: the authored map when one
+   directory's §8 index entry in the inspector: the authored map when one
    exists, the synthesized listing when not. */
 function showDir(dir){getIndex().then(dirs=>{const d=dirs.find(x=>x.dir===dir);if(!d)return;
  const opened=openPanel();sideBody.scrollTop=0;
@@ -1541,19 +1575,86 @@ function showDir(dir){getIndex().then(dirs=>{const d=dirs.find(x=>x.dir===dir);i
 function showLog(path){LOGS=null;getLogs().then(logs=>{const l=logs.find(x=>x.path===path);if(!l)return;
  const opened=openPanel();sideBody.scrollTop=0;
  shownId=path.replace(/\.md$/,'');
- sideBody.innerHTML=`<span class="type">update log · §7</span><h2 class="title">${esc(path)}</h2><div class="body" id="dir-body"></div>`;
+ sideBody.innerHTML=`<span class="type">update log · §9</span><h2 class="title">${esc(path)}</h2><div class="body" id="dir-body"></div>`;
  renderMarkdown(document.getElementById('dir-body'),l.content||'');
  if(opened)requestAnimationFrame(()=>cy.resize());});}
+/* ── §5 trust: one composition, both modes ──
+   The catalog row carries generated_at/generated_by, the raw `generated`
+   boolean, the derived `trust` tier (hyphenated, the wire spelling), the
+   declared `status` and `stale_after` — so every view can say how much to
+   believe a concept. Three rules, shared by the cards and the trust line:
+
+   · status  — only a NON-default one. §5.4 defaults an absent status to
+               `stable`, so badging that would chip every concept everywhere.
+   · trust   — suppressed when unverified AND `generated` is undeclared: on a
+               well-curated v0.1 bundle every concept has a lifted timestamp,
+               so keying off generated_at would label every card "unverified".
+               The raw boolean is the one predicate that gets this right.
+   · expired — computed HERE, against the viewer's own today. A baked verdict
+               is wrong from the next midnight and a static render lives for
+               months; the page compares dates the way the CLI does. */
+const TODAY=()=>{const d=new Date();return d.getFullYear()+'-'+String(d.getMonth()+1).padStart(2,'0')+'-'+String(d.getDate()).padStart(2,'0');};
+const isExpired=sa=>!!sa&&/^\d{4}-\d{2}-\d{2}$/.test(sa)&&TODAY()>=sa;
+/* One fold for every status keying — chips, facets, suppression — because the
+   row carries the DECLARED value and the CLI folds case when it narrows: a
+   `status: Stable` bundle otherwise grew duplicate facet chips filtering
+   disjoint sets, and "Stable" cards wore a chip the default never earns. The
+   raw spelling still renders as the chip's text; only keys fold. */
+const foldStatus=v=>{const s=String(v==null?'':v).trim().toLowerCase();return s||'stable';};
+/* The folded value is a filter key, not a class name: §4.1 lets a producer
+   declare `In Review`, which folded straight into the attribute became
+   `class="status in review"` — two classes a stylesheet may already own. One
+   token for the class, the raw spelling still the chip's text. */
+const statusSlug=v=>foldStatus(v).replace(/[^a-z0-9]+/g,'-').replace(/^-+|-+$/g,'')||'stable';
+const statusChip=c=>foldStatus(c.status)!=='stable'?`<span class="status ${esc(statusSlug(c.status))}">${esc(c.status)}</span>`:'';
+/* An `unverified` tier is an answer, not an absence — but only once a concept
+   declared `generated:`, since a v0.1 concept declaring neither would wear a
+   chip about a family it never had. The catalog's trust facet gates on this
+   same predicate: a tier shown on every card with no group to narrow on was
+   the shape it took when the two were spelled separately.
+
+   The rule's home is Ruby — Concept.shows_trust?, which the server's
+   /node/meta and okf-tui both ask. This is the client-side twin, unavoidable
+   because it runs over baked rows with no Ruby to call; a change to one is a
+   change to both, and render_test.rb pins them equal so the copy cannot drift
+   silently. */
+const showsTrust=c=>!!(c.trust&&!(c.trust==='unverified'&&!c.generated));
+const trustChip=c=>showsTrust(c)?`<span class="tier ${esc(c.trust)}">${esc(c.trust)}</span>`:'';
+/* No `by` means v0.1 lifted this from a `timestamp`, which recorded no actor.
+   Printing one would be the false provenance claim §5 exists to prevent. */
+const genChip=c=>c.generated_at?`<span class="mini">⌂ ${esc(c.generated_at)}${c.generated_by?' by '+esc(c.generated_by):''}</span>`:'';
 /* Two per-concept reads shared by the inspector and the files preview: the raw
-   markdown body (rendered client-side) and the description fragment. Live they
-   hit /node and /node/meta; under EMBED the body resolves from the baked payload
-   and the meta fragment is derived from the baked catalog — escaped here the same
-   way /node/meta escapes it — so the description lives in exactly one place.
-   Never memoized in server mode, so on-disk edits keep reflecting. */
-const EMBED_DESC=EMBED?Object.fromEntries((EMBED.catalog||[]).map(c=>[c.id,c.description||''])):null;
-const metaFragment=d=>(d==null||String(d).trim()==='')?'<span class="empty">no description</span>':esc(d);
+   markdown body (rendered client-side) and the meta object {description,trust}.
+   Live they hit /node and /node/meta (JSON); under EMBED both resolve from the
+   baked payload — the trust fields read off the same catalog row the cards use,
+   so the two modes compose one line from one ruleset. Never memoized in server
+   mode, so on-disk edits keep reflecting. */
+const EMBED_ROW=EMBED?Object.fromEntries((EMBED.catalog||[]).map(c=>[c.id,c])):null;
+const rowTrust=c=>{if(!c)return null;const t={};
+ if(showsTrust(c))t.tier=c.trust;
+ if(c.generated_by)t.generated_by=c.generated_by;
+ if(c.generated_at)t.generated_at=c.generated_at;
+ if(c.status)t.status=c.status;
+ if(c.stale_after)t.stale_after=c.stale_after;
+ return Object.keys(t).length?t:null;};
+const metaFromRow=c=>{const m={description:(c&&c.description)||''};const t=rowTrust(c);if(t)m.trust=t;return m;};
+/* The one place meta reaches the DOM. Every producer-supplied string lands via
+   textContent — never innerHTML — so no render path opens outside the
+   sanitizer the bodies already pass through. */
+function renderMeta(el,meta){el.textContent='';
+ const desc=String((meta&&meta.description)||'').trim();
+ if(desc)el.appendChild(document.createTextNode(desc));
+ else{const e=document.createElement('span');e.className='empty';e.textContent='no description';el.appendChild(e);}
+ const t=meta&&meta.trust;if(!t)return;
+ const line=document.createElement('span');line.className='meta-trust';
+ const chip=(cls,text)=>{const s=document.createElement('span');s.className=cls;s.textContent=text;line.appendChild(s);};
+ if(t.tier)chip('tier '+t.tier,t.tier);
+ if(t.generated_at)chip('gen',t.generated_at+(t.generated_by?' by '+t.generated_by:''));
+ if(foldStatus(t.status)!=='stable')chip('status '+statusSlug(t.status),t.status);
+ if(isExpired(t.stale_after))chip('stale','expired '+t.stale_after);
+ if(line.childNodes.length)el.appendChild(line);}
 function getNodeBody(id){return EMBED?Promise.resolve(EMBED.bodies[id]||''):fetch(NODE_ENDPOINT+'?id='+encodeURIComponent(id)).then(r=>r.ok?r.text():'');}
-function getNodeMeta(id){return EMBED?Promise.resolve(metaFragment(EMBED_DESC[id])):fetch(META_ENDPOINT+'?id='+encodeURIComponent(id)).then(r=>r.ok?r.text():'');}
+function getNodeMeta(id){return EMBED?Promise.resolve(metaFromRow(EMBED_ROW[id])):fetch(META_ENDPOINT+'?id='+encodeURIComponent(id)).then(r=>r.ok?r.json():{});}
 function show(id){const n=byId[id];if(!n)return false;const ty=typeOf[id]||'Untyped';const c=color[ty]||'#64748b';
  shownId=id;const opened=openPanel();sideBody.scrollTop=0;
  sideBody.innerHTML=`<button type="button" class="type facet" data-focus-type="${esc(ty)}" title="Show only ${esc(ty)} in the graph"><span class="dot" style="background:${c}"></span>${esc(ty)}</button>
@@ -1571,7 +1672,7 @@ function show(id){const n=byId[id];if(!n)return false;const ty=typeOf[id]||'Unty
  sideBody.querySelectorAll('[data-focus-tag]').forEach(b=>b.onclick=()=>{
   const t=b.getAttribute('data-focus-tag');tagFocused(t)?clearGraphFilter():focusGraphTag(t);});
  syncFacets();
- getNodeMeta(id).then(h=>{const d=document.getElementById('desc');if(d){d.innerHTML=h||'<span class="empty">no description</span>';d.classList.remove('loading');}}).catch(()=>{});
+ getNodeMeta(id).then(m=>{const d=document.getElementById('desc');if(d){renderMeta(d,m);d.classList.remove('loading');}}).catch(()=>{});
  const bodyEl=sideBody.querySelector('#body');
  getNodeBody(id).then(md=>{if(bodyEl.isConnected)renderMarkdown(bodyEl,md);}).catch(()=>{});
  return opened;}
@@ -1928,7 +2029,7 @@ function setTree(on){if(on===treeMode)return;if(on&&clustered)setClustered(false
   runLayout(layoutSel.value);}}
 btnTree.onclick=()=>setTree(!treeMode);
 /* ── the authored layer, drawn ──
-   The §6 map used to be visible only inside file-tree mode, where a folder node
+   The §8 map used to be visible only inside file-tree mode, where a folder node
    stood in for a directory's index.md. It is a layer of its own now: switch it
    on under any layout and each `index.md` becomes a node, edged to the concepts
    it maps and to the child maps beneath it. Cluster and tree mode still work —
@@ -2209,8 +2310,8 @@ document.querySelectorAll('.rail-item').forEach(b=>b.onclick=()=>{
 function loadMiniSearch(){return _MiniSearch||(_MiniSearch=loadScript('https://cdn.jsdelivr.net/npm/minisearch@7.2.0/dist/umd/index.js').then(()=>window.MiniSearch));}
 function buildFtIndex(){return ftIndex?Promise.resolve(ftIndex):(ftBuilding||(ftBuilding=Promise.all([loadMiniSearch(),getCatalog()]).then(([MiniSearch,list])=>{
  const idx=new MiniSearch({idField:'id',fields:FT_FIELDS,storeFields:['id'],
-  extractField:(doc,f)=>f==='tags'?(doc.tags||[]).join(' '):f==='body'?((EMBED&&EMBED.bodies[doc.id])||''):(doc[f]==null?'':String(doc[f])),
-  searchOptions:{prefix:true,fuzzy:0.2,combineWith:'AND',boost:{title:5,id:4,tags:3,type:2,description:2,body:1}}});
+  extractField:(doc,f)=>f==='tags'?(doc.tags||[]).join(' '):f==='body'?((EMBED&&EMBED.bodies[doc.id])||''):f==='sources'?((EMBED&&EMBED.sources[doc.id])||''):(doc[f]==null?'':String(doc[f])),
+  searchOptions:{prefix:true,fuzzy:0.2,combineWith:'AND',boost:{title:5,id:4,tags:3,type:2,description:2,sources:1,body:1}}});
  idx.addAll(list);ftIndex=idx;
  if((view==='graph'||view==='catalog'||view==='files')&&(q[view]||'').trim())applySearch();
  return idx;}).catch(()=>{ftBuilding=null;return null;})));}
@@ -2242,11 +2343,30 @@ let CATALOG=null;
    otherwise) and fills descOf on the way, so even the pre-index substring
    fallback can match a graph node by its leaf description. */
 function getCatalog(){return CATALOG||(CATALOG=(EMBED?Promise.resolve(EMBED.catalog):fetch(CATALOG_ENDPOINT).then(r=>r.json()).then(d=>d.concepts)).then(list=>{list.forEach(c=>{descOf[c.id]=c.description||'';});return list;}));}
-const catActiveTypes=new Set(), catActiveDirs=new Set(), catActiveTags=new Set();
+const catActiveTypes=new Set(), catActiveDirs=new Set(), catActiveTags=new Set(),
+ catActiveStatus=new Set(), catActiveTrust=new Set();
+/* The two §5 facets, counted off the catalog — it is the only payload that
+   knows them, so they cannot be built at boot like types and tags. Status
+   counts the EFFECTIVE value (absent reads stable, the same rule --status
+   narrows by); trust counts the derived tier. A facet with nothing to say
+   stays hidden: the status group needs at least one DECLARED status, and the
+   trust group at least one concept whose tier the page is willing to claim —
+   otherwise every v0.1 bundle would wear a row of chips saying only
+   "unverified". `showsTrust` is that willingness, and all three of the gate,
+   the counts and the narrowing read it, so the facet describes exactly the
+   cards wearing a tier chip. Counting rows the page shows no chip for made it
+   read "unverified 3" over two chipped cards, and narrow to three. */
+let catStatusCounts={}, catTrustCounts={}, catShowStatus=false, catShowTrust=false;
+function catFacets(list){catStatusCounts={};catTrustCounts={};catShowTrust=false;
+ list.forEach(c=>{const s=foldStatus(c.status);catStatusCounts[s]=(catStatusCounts[s]||0)+1;
+  if(showsTrust(c)){catTrustCounts[c.trust]=(catTrustCounts[c.trust]||0)+1;catShowTrust=true;}});
+ catShowStatus=list.some(c=>c.status);}
+const facetByCount=counts=>Object.keys(counts).sort((a,b)=>counts[b]-counts[a]||a.localeCompare(b));
+const facetItems=counts=>facetByCount(counts).map(v=>({v:v,n:counts[v]}));
 const catByCount=types.slice().sort((a,b)=>(TYPES[b]||[]).length-(TYPES[a]||[]).length);
 const catChip=t=>`<span class="chip" data-t="${esc(t)}"><span class="dot" style="background:${color[t]}"></span>${esc(t)} <span class="c">${(TYPES[t]||[]).length}</span></span>`;
 function syncCatChips(){document.querySelectorAll('#cat-types .chip').forEach(c=>c.classList.toggle('on',catActiveTypes.has(c.getAttribute('data-t'))));
- const n=catActiveTypes.size+catActiveDirs.size+catActiveTags.size;
+ const n=catActiveTypes.size+catActiveDirs.size+catActiveTags.size+catActiveStatus.size+catActiveTrust.size;
  const b=document.getElementById('cat-filters-btn');b.classList.toggle('on-filter',n>0);b.querySelector('.fbadge').textContent=n;}
 function catToggle(t){toggleSet(catActiveTypes,t);renderCatFilters();renderCatalog();}
 function wireCatChips(el){el.querySelectorAll('.chip').forEach(ch=>ch.onclick=()=>catToggle(ch.getAttribute('data-t')));}
@@ -2258,6 +2378,11 @@ function renderCatFilters(){const qq=(document.getElementById('cat-filter-search
  chipRow(document.getElementById('cat-ftypes'),typeItems(catByCount.filter(match)),'data-t',t=>catActiveTypes.has(t),t=>{toggleSet(catActiveTypes,t);after();});
  chipRow(document.getElementById('cat-fdirs'),dirItems(graphDirs.filter(dirMatch(qq))),'data-dir',d=>catActiveDirs.has(d),d=>{toggleSet(catActiveDirs,d);after();});
  chipRow(document.getElementById('cat-ftags'),tagItems(qq?tagsByCount.filter(match):tagsByCount.slice(0,40)),'data-tag',t=>catActiveTags.has(t),t=>{toggleSet(catActiveTags,t);after();});
+ const sItems=facetItems(catStatusCounts).filter(o=>match(o.v)), tItems=facetItems(catTrustCounts).filter(o=>match(o.v));
+ document.getElementById('cat-fstatus-group').hidden=!(catShowStatus&&sItems.length);
+ document.getElementById('cat-ftrust-group').hidden=!(catShowTrust&&tItems.length);
+ chipRow(document.getElementById('cat-fstatus'),sItems,'data-status',s=>catActiveStatus.has(s),s=>{toggleSet(catActiveStatus,s);after();});
+ chipRow(document.getElementById('cat-ftrust'),tItems,'data-trust',t=>catActiveTrust.has(t),t=>{toggleSet(catActiveTrust,t);after();});
  syncCatChips();}
 function initCatalog(){inited.catalog=true;
  // Only the five most common types get inline chips; everything else — types,
@@ -2268,13 +2393,18 @@ function initCatalog(){inited.catalog=true;
  const cf=document.getElementById('cat-filters');
  document.getElementById('cat-filters-btn').onclick=()=>cf.classList.toggle('open');
  document.getElementById('cat-filters-close').onclick=()=>cf.classList.remove('open');
- document.getElementById('cat-filters-reset').onclick=()=>{catActiveTypes.clear();catActiveDirs.clear();catActiveTags.clear();renderCatFilters();renderCatalog();};
+ document.getElementById('cat-filters-reset').onclick=()=>{catActiveTypes.clear();catActiveDirs.clear();catActiveTags.clear();
+  catActiveStatus.clear();catActiveTrust.clear();renderCatFilters();renderCatalog();};
  document.getElementById('cat-filter-search').oninput=renderCatFilters;
- getCatalog().then(renderCatalog);}
+ // The §5 facets only exist once the catalog is in, so the panel renders
+ // twice: the chips boot knows immediately, then the two that had to wait.
+ getCatalog().then(list=>{catFacets(list);renderCatFilters();renderCatalog();});}
 function renderCatalog(){if(!CATALOG)return;getCatalog().then(list=>{const s=(q.catalog||'').toLowerCase();const ids=ftMatch(q.catalog);
  const rows=list.filter(c=>{if(catActiveTypes.size&&!catActiveTypes.has(c.type))return false;
   if(catActiveDirs.size&&![...catActiveDirs].some(d=>underDir(dirOf(c.id),d)))return false;
   if(catActiveTags.size&&!c.tags.some(t=>catActiveTags.has(t)))return false;
+  if(catActiveStatus.size&&!catActiveStatus.has(foldStatus(c.status)))return false;
+  if(catActiveTrust.size&&!(showsTrust(c)&&catActiveTrust.has(c.trust)))return false;
   if(ids)return ids.has(c.id);
   if(s){const hay=(c.title+' '+c.description+' '+c.type+' '+c.tags.join(' ')+' '+c.id).toLowerCase();if(!hay.includes(s))return false;}return true;});
  document.getElementById('cat-cnt').textContent=rows.length+' of '+list.length+' concepts';
@@ -2284,14 +2414,16 @@ function renderCatalog(){if(!CATALOG)return;getCatalog().then(list=>{const s=(q.
  const g=document.getElementById('cat-grid');
  if(!rows.length){g.innerHTML='<div class="none">No concepts match — try clearing the filters.</div>';return;}
  g.innerHTML=rows.map(c=>{const cc=color[c.type]||'#64748b';
-  const st=c.status?`<span class="status ${c.status==='shipped'?'shipped':''}">${esc(c.status)}</span>`:'';
+  const st=statusChip(c);
+  const tr=trustChip(c);
   const tags=c.tags.slice(0,4).map(t=>`<span class="tag">${esc(t)}</span>`).join('');
-  const ts=c.timestamp?`<span class="mini">⌂ ${esc(c.timestamp)}</span>`:'';
+  const ts=genChip(c);
+  const sa=isExpired(c.stale_after)?`<span class="mini stale">⚠ expired ${esc(c.stale_after)}</span>`:'';
   const lk=(c.links_out+c.links_in)?`<span class="mini links">↳ ${c.links_out+c.links_in} links</span>`:'';
   return `<article class="card" tabindex="0" data-id="${esc(c.id)}">
-   <div class="r1"><span class="badge"><span class="dot" style="background:${cc}"></span>${esc(c.type)}</span>${st}<span class="area">${esc(c.dir)}/</span></div>
+   <div class="r1"><span class="badge"><span class="dot" style="background:${cc}"></span>${esc(c.type)}</span>${st}${tr}<span class="area">${esc(c.dir)}/</span></div>
    <h3>${esc(c.title)}</h3><p class="cd">${esc(c.description)||'<span class="empty">No description.</span>'}</p>
-   <div class="cm">${tags}${ts}${lk}</div></article>`;}).join('');
+   <div class="cm">${tags}${ts}${sa}${lk}</div></article>`;}).join('');
  g.querySelectorAll('.card').forEach(el=>{const id=el.dataset.id;el.onclick=()=>goToGraph(id);
   el.onkeydown=e=>{if(e.key==='Enter'||e.key===' '){e.preventDefault();goToGraph(id);}};});});}
 
@@ -2502,11 +2634,11 @@ function openReserved(kind,path){fileSel=path;
  const body=document.getElementById('fp-body');body.innerHTML='<p class="loading">loading…</p>';
  const done=txt=>{const wrap=document.createElement('div');wrap.className='body';renderMarkdown(wrap,txt);body.innerHTML='';body.appendChild(wrap);};
  if(kind==='index')getIndex().then(dirs=>{const d=dirs.find(x=>x.dir===dirOfPath(path));
-  type.textContent=d&&d.synthesized?'directory index · synthesized':'directory index · §6';
+  type.textContent=d&&d.synthesized?'directory index · synthesized':'directory index · §8';
   if(d&&d.synthesized){body.innerHTML='<div class="body">'+listingHtml(d.listing)+'</div>';
    body.querySelectorAll('[data-go]').forEach(x=>x.onclick=()=>openFile(x.getAttribute('data-go')));}
   else done((d&&d.body)||'');});
- else{type.textContent='update log · §7';
+ else{type.textContent='update log · §9';
   LOGS=null;getLogs().then(logs=>{const l=logs.find(x=>x.path===path);done((l&&l.content)||'');});}}
 
 /* ── tags ── */
@@ -2584,13 +2716,13 @@ const fsOn=()=>document.fullscreenElement===appEl;
 btnFull.onclick=()=>{if(fsOn())document.exitFullscreen();else if(appEl.requestFullscreen)appEl.requestFullscreen();};
 document.addEventListener('fullscreenchange',()=>btnFull.setAttribute('aria-pressed',String(fsOn())));
 
-/* ── the §6 map payload — feeds folder clicks, the Indexes tab, and previews ── */
+/* ── the §8 map payload — feeds folder clicks, the Indexes tab, and previews ── */
 let INDEX=null;
 function getIndex(){return INDEX||(INDEX=EMBED?Promise.resolve(EMBED.index):fetch(INDEX_ENDPOINT).then(r=>r.json()).then(d=>d.directories));}
 function listingHtml(items){if(!items||!items.length)return '<p class="empty" style="margin:10px 0 0">No concepts directly here.</p>';
  return '<ul class="ix-listing">'+items.map(it=>`<li><a data-go="${esc(it.id)}">${esc(it.title||it.id)}</a>${it.description?` <span class="d">— ${esc(it.description)}</span>`:''}</li>`).join('')+'</ul>';}
 
-/* ── log payload (the §7 history) — read by the Files view's log entries ── */
+/* ── log payload (the §9 history) — read by the Files view's log entries ── */
 let LOGS=null;
 function getLogs(){return LOGS||(LOGS=EMBED?Promise.resolve(EMBED.logs):fetch(LOG_ENDPOINT).then(r=>r.json()).then(d=>d.logs));}
 
@@ -3215,8 +3347,8 @@ function bridgeReport(v,shown,total){if(bridge)bridge.report(v,shown,total);}
    '<p class="pv-meta">'+out+' link'+(out===1?'':'s')+' out · '+inn+' in</p>';
   bodyIn.innerHTML=relList('Links to',outL[id]||[])+relList('Linked from',inL[id]||[])+'<div class="body" id="pv-md"></div>';
   bodyIn.querySelectorAll('[data-go]').forEach(a=>a.onclick=()=>select(a.getAttribute('data-go')));
-  getNodeMeta(id).then(h=>{const d=document.getElementById('pv-desc');
-   if(d&&shown===id){d.innerHTML=h||'<span class="empty">no description</span>';d.classList.remove('loading');}}).catch(()=>{});
+  getNodeMeta(id).then(m=>{const d=document.getElementById('pv-desc');
+   if(d&&shown===id){renderMeta(d,m);d.classList.remove('loading');}}).catch(()=>{});
   if(snap!=='peek')loadBody();
   return true;}
  /* lazy: the body is markdown nobody can see at peek, and on a phone peek is the
@@ -3245,7 +3377,7 @@ function bridgeReport(v,shown,total){if(bridge)bridge.report(v,shown,total);}
   bodyIn.querySelectorAll('[data-go]').forEach(a=>a.onclick=()=>select(a.getAttribute('data-go')));
   raise();}).catch(function(){});}
  function fillLog(path){LOGS=null;getLogs().then(function(logs){const l=logs.find(x=>x.path===path);if(!l)return;
-  renderMarkdown(fillHead('update log · §7',path,'the §7 history'),l.content||'');
+  renderMarkdown(fillHead('update log · §9',path,'the §9 history'),l.content||'');
   raise();}).catch(function(){});}
 
  /* ---- the camera -------------------------------------------------------- */

data/lib/okf/render/graph.rb

@@ -55,14 +55,22 @@ module OKF
       # answer. Every key here is data a client getter reads from EMBED instead of
       # fetching — and each derives from the *same* folder method the matching
       # OKF::Server::App endpoint uses, so the bake and the live server cannot
-      # drift (/node/meta is the exception: the fragment is derived on the client
-      # from the catalog's raw description, so no map is baked for it).
+      # drift (/node/meta is the exception: the trust line is composed on the
+      # client from the catalog row, so no map is baked for it). `bodies` and
+      # `sources` have no bare endpoint at all — they exist so a static file
+      # searches offline what the server-mode index deliberately leaves out; the
+      # sources text is the same join the Ruby engines index, so `--engine index`
+      # and the baked page rank identically. Empty strings are baked too: an
+      # undefined getter throws client-side.
       def self.payload(folder)
         {
           catalog: folder.catalog,
           index: folder.directory_index,
           logs: folder.log_entries,
-          bodies: folder.concepts.each_with_object({}) { |concept, map| map[concept.id] = concept.body.to_s }
+          bodies: folder.concepts.each_with_object({}) { |concept, map| map[concept.id] = concept.body.to_s },
+          sources: folder.concepts.each_with_object({}) do |concept, map|
+            map[concept.id] = OKF::Bundle::Search.field_texts(concept)["sources"]
+          end
         }
       end
 

data/lib/okf/safe_read.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "path"
+
+module OKF
+  # Shell-side containment for reads. `Path.under?` is the pure decision; the
+  # `File.realpath` that feeds it is disk I/O, so it lives here, out of the pure
+  # core. Every byte a bundle serves is read through this one primitive — the
+  # Reader's bulk load, `Concept::File`, the live `log.md` re-read, the MCP
+  # shell's concept and index reads — so a symlink whose name sits inside the
+  # root but whose target does not is refused in exactly one place. A read that
+  # rolled its own check could quietly drift and reopen the escape; there is
+  # nothing to drift from here.
+  #
+  # Scope. This closes the escape a *symlink* opens — the one a bundle can carry
+  # through a git clone, a copy or a tarball, which is the portable, adversarial
+  # case (a shared bundle whose author points a link at your secrets). It does
+  # not close a *hardlink*: File.realpath cannot resolve one (a hardlink shares
+  # its target's inode and keeps its own in-root path), and the obvious guard —
+  # rejecting st_nlink > 1 — would break a bundle on a deduplicating filesystem
+  # (a Nix store, some CI caches) where ordinary files legitimately share links.
+  # A hardlink to an outside file requires local write access to the served
+  # directory on the target's own filesystem, and cannot survive being copied,
+  # so it is a narrower, non-portable threat left deliberately out of scope.
+  module SafeRead
+    module_function
+
+    # The file's real, symlink-resolved location, or Path::Error if it escapes
+    # +root+. Pass +real_root+ when resolving many paths under one root (the
+    # Reader's loop) so the root is resolved once, not per file.
+    def contained_path!(root, path, real_root: nil)
+      real = ::File.realpath(path)
+      real_root ||= ::File.realpath(root)
+      raise Path::Error, "symlink target escapes bundle root" unless Path.under?(real_root, real)
+
+      real
+    end
+
+    # +path+'s bytes, read from its *resolved* location — so a symlink swapped in
+    # anywhere but the final component is caught, since the resolved path has no
+    # links left to follow — and refused if it escapes. The microscopic window
+    # between resolving and opening the leaf is not closed here (that needs an
+    # open-by-descriptor the 2.4 stdlib does not lend itself to); reading the
+    # resolved path is strictly better than reading the caller's raw name, which
+    # re-followed every link on every read.
+    def read!(root, path, real_root: nil, encoding: "UTF-8")
+      ::File.read(contained_path!(root, path, real_root: real_root), encoding: encoding)
+    end
+  end
+end