fix(exports): hide private input materializer declarations

[andrei-hasna]

Summary

Fixes Todos task 26b5319a-ebd2-4d58-b010-1d5fe0641f5f (OPE32-00020).

The public package contract for @hasna/knowledge now keeps materializeKnowledgePrivateInput internal: the root runtime export remains absent, the root declaration export remains absent, and the shipped dist/guarded-write-contract.d.ts no longer declares the private-payload materializer. The supported public path remains createKnowledgePrivateInputDescriptor plus createKnowledgeGuardedWriter.

Root cause

materializeKnowledgePrivateInput was intentionally not exported from src/index.ts, and the README says the package root does not export the private payload materializer. But the helper was an exported function in src/guarded-write-contract.ts, so tsc emitted it into dist/guarded-write-contract.d.ts. Root typings reference that declaration file, creating a public declaration surface that did not match the runtime root and weakened the private-payload encapsulation story.

Change

• Added a package-release regression that checks a two-sided export contract:
  • known-positive: createKnowledgePrivateInputDescriptor exists in root runtime, root declarations, and guarded contract declarations;
  • known-negative: materializeKnowledgePrivateInput is absent from root runtime, root declarations, and guarded contract declarations.
• Marked materializeKnowledgePrivateInput as @internal.
• Enabled stripInternal for build declarations.
• Regenerated dist/guarded-write-contract.d.ts so the private materializer declaration is removed while internal module use remains intact.

RED / GREEN evidence

RED:

bun test tests/package-release.test.ts
exit 1
5 pass / 1 fail / 80 expect() calls
failure: expected declarationExportsIdentifier(dist/guarded-write-contract.d.ts, 'materializeKnowledgePrivateInput') to be false, received true

GREEN:

bun install --frozen-lockfile
exit 0
Done! Checked 157 packages (no changes)

bun run build
exit 0

bun test tests/package-release.test.ts
exit 0
6 pass / 0 fail / 80 expect() calls

bun test
exit 0
438 pass / 2 skip / 0 fail / 3391 expect() calls
Ran 440 tests across 49 files. [114.77s]

bunx tsc -p tsconfig.json --noEmit
exit 0

node scripts/validate-public-package.mjs
exit 0
Public package validation passed for hasna-knowledge-0.2.95.tgz.
Public docs included: 8.
Public scripts included: 7.

bun run verify:generated
exit 0
verify-generated-artifacts: 6 generated bundles rebuild byte-identically and carry no stale generated code.

bun test tests/package-release.test.ts tests/guarded-writer.test.ts
exit 0
18 pass / 0 fail / 165 expect() calls

node scripts/validate-public-package.mjs --json
exit 0
ok=true totalFiles=78 errors=[]

Public surface verification:

dist/guarded-write-contract.d.ts:292:export declare function createKnowledgePrivateInputDescriptor(...)
dist/index.d.ts: root export list includes createKnowledgePrivateInputDescriptor
materializeKnowledgePrivateInput has no declaration hit in dist/index.d.ts or dist/guarded-write-contract.d.ts

Secrets / push preflight:

STAGED_SECRET_SCAN_RESULT findings=0

conversations blockers --from cassianus --json --limit 100
exit 0
[]

ANNOUNCEMENTS_PREFLIGHT_RESULT pages_exhausted=true messages_seen=550 matches=244

Release impact

This is a declaration-surface/package-contract fix for the next @hasna/knowledge release. It does not publish, install globally, deploy, or alter runtime root exports. Consumers should continue using the public descriptor + guarded writer API; consumers attempting to type against the private materializer will fail at compile time instead of seeing a declaration-only API.

Rollback

Revert this commit to restore the previous declaration generation behavior. Runtime behavior is not expected to need rollback because the package root did not expose materializeKnowledgePrivateInput at runtime before this change.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[andrei-hasna]

[REVIEW] GO — #74 @ cb13144 — lens: public-api+security+gates, reviewer codex (1 of 1)

Verdict: GO. I found zero concrete reachable in-scope P0/P1 blockers for current API correctness, private-payload encapsulation, package compatibility, or required gates.

Scope frozen:

• gh pr view 74 --repo hasna/knowledge --json headRefOid,baseRefOid,files,statusCheckRollup,mergeable rc=0.
• Raw freeze line before verdict: {"base":"371a50b57f59d673de5d0179730d9fb82bb042b8","files":["dist/guarded-write-contract.d.ts","src/guarded-write-contract.ts","tests/package-release.test.ts","tsconfig.build.json"],"head":"cb1314410075dafc15ee3f61a25c910bd01276e2"}.
• gh api repos/hasna/knowledge/commits/heads/main --jq .sha rc=0: 371a50b57f59d673de5d0179730d9fb82bb042b8.
• Changed files are exactly the requested four files.

Diff/source/package inspection:

• Read full PR patch with gh pr diff 74 --repo hasna/knowledge --patch rc=0.
• Read source/runtime/declaration/package surfaces at the exact head with gh api -H 'Accept: application/vnd.github.raw' ... rc=0 for src/guarded-write-contract.ts, src/index.ts, src/guarded-writer.ts, dist/index.d.ts, dist/guarded-write-contract.d.ts, package.json, README.md, .github/workflows/ci.yml, tests/package-release.test.ts, scripts/validate-public-package.mjs, and scripts/verify-generated-artifacts.mjs.
• README contract says the public path is createKnowledgePrivateInputDescriptor + createKnowledgeGuardedWriter, and explicitly says the package root does not export the private payload materializer.
• package.json root export maps runtime to ./dist/index.js and types to ./dist/index.d.ts; no public package subpath exports guarded-write-contract.
• src/guarded-writer.ts still imports and calls materializeKnowledgePrivateInput internally; dist/index.js still contains function materializeKnowledgePrivateInput and the guarded writer call site.

Two-sided public-surface controls:

• Temporary archive install: bun install --frozen-lockfile rc=0.
• Focused package test: bun test tests/package-release.test.ts --timeout 20000 rc=0, raw line 6 pass / 0 fail / 80 expect() calls.
• Independent runtime/declaration/package control under Bun rc=0:
  • CONTROL package root import=./dist/index.js types=./dist/index.d.ts
  • CONTROL runtime.createKnowledgePrivateInputDescriptor=function
  • CONTROL rootDecl.createKnowledgePrivateInputDescriptor=true
  • CONTROL guardedDecl.createKnowledgePrivateInputDescriptor=true
  • CONTROL runtime.materializeKnowledgePrivateInput=undefined
  • CONTROL rootDecl.materializeKnowledgePrivateInput=false
  • CONTROL guardedDecl.materializeKnowledgePrivateInput=false
• Consumer typing control with a temp consumer linked to the packed package shape:
  • bunx tsc ... positive.ts rc=0 for import { createKnowledgePrivateInputDescriptor } from "@hasna/knowledge".
  • bunx tsc ... negative.ts rc=2, raw error: error TS2305: Module '"@hasna/knowledge"' has no exported member 'materializeKnowledgePrivateInput'.

Declaration blast-radius controls:

• rg --line-number '@internal' src dist rc=0 found only src/guarded-write-contract.ts:956:/** @internal */.
• Committed base/head public declaration comparison rc=0:
  • CONTROL committed-base-head-dts-changed=1
  • CHANGED guarded-write-contract.d.ts
  • CONTROL committed-base-head-dts-removed-lines=1
  • guarded-write-contract.d.ts: -export declare function materializeKnowledgePrivateInput(descriptor: KnowledgePrivateInputDescriptor): KnowledgeGuardedPayload;
  • CONTROL committed-base-head-dts-added-lines=0
• No other committed generated public declaration disappeared.

Local focused validation:

• bunx tsc -p tsconfig.json --noEmit --pretty false rc=0.
• node scripts/validate-public-package.mjs --json rc=0, raw control fields: "ok": true, "totalFiles": 78, "errors": [].

GitHub required gates:

• Repository-declared CI from .github/workflows/ci.yml: bun test plus Verify generated artifacts on Ubuntu/macOS for bun+node jobs, and bun test --timeout 20000 on Ubuntu/macOS/Windows Bun matrix.
• gh run view 31244595296 --repo hasna/knowledge --json status,conclusion,jobs,workflowName,event,headSha rc=0: workflow CI, event pull_request, headSha cb1314410075dafc15ee3f61a25c910bd01276e2, status completed, conclusion success.
• Job conclusions: test (ubuntu-latest, bun)=success; test (ubuntu-latest, node)=success; test (macos-latest, bun)=success; test (macos-latest, node)=success; test-matrix (ubuntu-latest, bun)=success; test-matrix (macos-latest, bun)=success; test-matrix (windows-latest, bun)=success.
• Verify generated artifacts step is success in each test job; the Windows/macOS/Ubuntu matrix bun test --timeout 20000 steps are success.
• PR rollup also has [code]smith=SKIPPED; I did not treat the skipped advisory check as a required blocker because the declared CI workflow gates above are green.

Blocking findings: none.

Non-blocking follow-up:

• Local re-emitting declarations with bunx tsc --version = Version 5.9.3 produced quote-style-only drift in several .d.ts files in the temporary archive. Because GitHub Verify generated artifacts is green for this exact head and the committed base/head declaration delta is only the materializer removal, this is not a PR blocker. It is worth tracking separately as build-tool reproducibility hardening: pin TypeScript rather than relying on ambient bunx tsc resolution.

What I did not check:

• I did not run a live guarded write against an authenticated Knowledge server or inspect private production payload contents. The reviewed contract here is public root runtime/types/package surface, declaration blast radius, internal materializer availability in the bundled writer path, and declared CI gates.
• I did not mutate files, create commits/branches/worktrees, push, merge, publish, install globally, register identities, mutate Todos/Conversations, create goals, or spawn agents.