Skip to content

feat(v2): TL-U10 offline thl CLI and confined Node host with packed proof - #43

Merged
christophersesugh merged 71 commits into
mainfrom
feat/tl-u10-cli-host-security
Nov 15, 2026
Merged

christophersesugh merged 71 commits into
mainfrom
feat/tl-u10-cli-host-security

Conversation

@christophersesugh

@christophersesugh christophersesugh commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

TL-U10 — Offline CLI, reviewed sidecars, secure Remark host and verified schema-2 package

Verified source head: 74cf26006047baed29973ea5df6a35d0d8887a97.
Review status: ready for maintainer review. Not merged, tagged, published or deployed.

Delivered

  • Standalone Node 24+ thl executable: validate artifact.json strictly parses, validates and compiles a schema-2 model; materialize --document FILE --ordinal N --artifact FILE --manifest FILE creates/updates a deterministic, canonical SHA-256-bound version-1 manifest entry; check FILE_OR_DIR [--manifest FILE] inspects Markdown and MDX fences without running the documents, validates direct JSON inline, and refuses unresolved, stale, malformed and unreviewed prose. Supports explicit trusted --root ROOT; the default is the invoked current directory.
  • Review boundary: every materialization resets the exact entry to unreviewed, including re-materialization of previously approved entries. Approval requires an independent human/source-control review. No approve shortcut, network call, AI invocation, arbitrary plugin import or automatic materialization.
  • Node-only trusted host: independently exported @0xbuff/throughline/node provides createNodeThroughlineHost({root,manifestPath?}), validating strict manifest JSON (including duplicate-key rejection), confining VFile locators and artifact reads to the configured real root, rejecting traversal, encoded aliases, unsafe/absolute paths and symlink paths, bounding UTF-8 files, and using atomic manifest writes. The pure root, optional ./remark, and ./react do not depend on the Node-only host.
  • Unqualified fence grammar: supports direct strict schema-2 JSON without a sidecar and reviewed prose sidecars with LF-normalized mdast body digests. Rejects domain metadata, unsupported envelope versions, conflicting mutations, invalid references and expired review; diagnostics include stable THL_* codes and file/line/ordinal when known. Unrelated Markdown, math and Mermaid are left unchanged.
  • No backward-compatibility adapter: removed schema-1 compile, domain names, old trace models and ThroughlinePlayer from public package exports; preserved historical regressions via internal source imports only. Native public interfaces are compileArtifact, queries, projections, ThroughlineGraphPlayer, ThroughlineEmbed, one thl fence and separate host/CLI entrypoints. Browser capability detection was also fixed to be hydration-stable.
  • Docs: added offline CLI and review guide, updated framework/README/release guidance and checked the CLI executable, exports, declaration files and source-map handling in the package build.

Maintainer review fixes — actual Markdown/MDX nodes and public architecture

  • P1: Replaced the raw-line fence heuristic in src/node/markdown.ts with unified, remark-parse and remark-mdx. CLI discovery now uses the same non-evaluating mdast code-node semantics as the Remark host, in depth-first order. Markdown and MDX files use their respective parser formats. Nested list/blockquote/JSX fences are recognized; HTML comments, JavaScript strings and MDX expression comments never create false code-node ordinals. Source body and positions come from the AST, and malformed MDX fails closed. Bounded input size, AST depth/work and stable sanitized diagnostics remain in place.
  • New regressions reproduce the reviewer's exact nested-list failure, independently compare CLI results to actual mdast nodes and positions, and require both check and materialize to find nested blocks. Tests also reject fake fences in HTML comments and expressions. The independently installed npm tarball CLI verifies the same nested-list materialization and human-review gate.
  • Explicit Node syntax dependencies remark-parse@11.0.0, remark-mdx@3.1.1 and unified@11.0.5 are pinned, separately licensed and externalized; pnpm-lock.yaml was regenerated and committed. The temporary branch-scoped lockfile-generation workflow was removed immediately afterward. No React/AI/network dependency was added to the pure compiler.
  • P2: Replaced docs/architecture.md with schema-2 VisualArtifact validation, compileArtifact, inspectTrace, projectView, projectInspection, ThroughlineGraphPlayer and ThroughlineEmbed plus the trusted Markdown/CLI boundaries. AGENTS.md now accurately lists public entry points and forbids v1 domain/parser/player exports or compatibility. The CLI guide and changelog were aligned.
  • Verification on exact head 74cf260: Throughline CI https://github.com/0xbuffdev/throughline/actions/runs/43718558351 PASSED (CLI/typecheck, tests, packed Node/Remark/MDX, browser SSR/hydration, Fumadocs/Next/Astro, Markdown hosts and license/source audits); Firefox/WebKit https://github.com/0xbuffdev/throughline/actions/runs/43718558303 both PASSED.

Independent verification (actual packed package)

  • CLI unit/security tests cover validate/materialize/check, strict duplicate JSON keys, unreviewed/stale/tampered source/model, nested Markdown/code-block ordinals, source coordinates, unknown commands, unsafe paths and symlink escapes. VG-01 direct-JSON and prose approval are exercised offline.
  • pnpm pack tarball is installed in a clean Node-only consumer first, verifies actual thl binary execution and manually reviewed sidecar workflow, followed by independently installed Remark, React SSR, MDX, and typed consumers.
  • Browser checks verify native schema-2 React SSR hydration, mobile styling, keyboard/touch controls, view switching and absence of v1 public exports. Framework tests verify independent Fumadocs, Next.js, Astro and Markdown host consumers while keeping math/Mermaid and other code unchanged.
  • Throughline CI #43718558351 — passed on exact head, including typechecking, pure tests, Chromium browser, build, source/license audits, packed Node/Remark/React/MDX, Vite hydration, framework and Markdown-host consumers.
  • Firefox/WebKit QA #43718558303 — both passed.

Separate real-docs handoff (not a deployment)

  • 0xbuffdev/documentation PR #15 is a draft, CI-passing implementation handoff for TL-U20. It records actual Fumadocs MDX plugin, content, demo, component-map, math/Mermaid and deployment migration steps without altering the installed legacy 0.0.2 dependency, lockfile, runtime integration or live site.
  • The registry release is TL-U19, and the real docs version upgrade and staged deployment is TL-U20. Neither happens as part of TL-U10. No performance/comprehension superiority or real payment guarantee is claimed.

Maintainer handoff

Please review and merge this source PR when satisfied; I have not merged it. TL-U10 status remains open until the reviewed merge/acceptance; no architecture-ticket archive operation was performed. The separate documentation preparation PR should remain draft until TL-U20 release gating.

@christophersesugh
christophersesugh marked this pull request as ready for review November 15, 2026 12:48

@christophersesugh christophersesugh left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed TL-U10 against accepted Throughline Specification 0004 §13, ADR-0005, the active ticket, and the package boundary. Two actionable findings are annotated inline. GitHub reports green CI/Firefox/WebKit on this head; I could not run this repository's test suite locally. Please address the validation-gate discrepancy before merging. No merge or approval action taken.

Comment thread src/node/markdown.ts Resolved
Comment thread src/index.ts Resolved
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Deploying throughline with  Cloudflare Pages  Cloudflare Pages

Latest commit: 63b8587
Status: ✅  Deploy successful!
Preview URL: https://0a07a921.throughline-218.pages.dev
Branch Preview URL: https://feat-tl-u10-cli-host-securit.throughline-218.pages.dev

View logs

christophersesugh and others added 15 commits November 15, 2026 14:12
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@christophersesugh
christophersesugh merged commit bb1bc37 into main Nov 15, 2026
3 checks passed
@christophersesugh
christophersesugh deleted the feat/tl-u10-cli-host-security branch November 15, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant