Skip to content

feat(kernel): register the @hcs/kernel workspace - #97

Merged
verlyn13 merged 1 commit into
mainfrom
feat/kernel-workspace-scaffold
Jul 25, 2026
Merged

feat(kernel): register the @hcs/kernel workspace#97
verlyn13 merged 1 commit into
mainfrom
feat/kernel-workspace-scaffold

Conversation

@verlyn13

Copy link
Copy Markdown
Member

What

First non-.gitkeep file in Ring 1. packages/kernel/ has held an empty marker since the repo was scaffolded.

Three files: a package manifest, an empty public-API barrel, and a test suite that guards the ring boundary.

Change class: D — kernel, read path.

The exports map is the point

charter §Package boundary enforcement:

packages/adapters/** cannot import from packages/kernel/src/** except through the declared public API surface (packages/kernel/src/api/).

That rule now has two independent enforcers:

  1. scripts/ci/boundary-check.sh rule 2 — a grep. It went three months without executing once: a PCRE lookahead under grep -E exited rc=2 and 2>/dev/null ate the diagnostic, so it printed ✓ ring boundaries intact while a planted violation passed. Repaired in fix(ci): make grep gates and node-tool gates fail closed #93.
  2. This package's exports map, which publishes . and ./api and nothing else.

The second is the durable one. A grep can regress silently; a missing exports entry cannot. Verified on this host:

$ node -e "import('@hcs/kernel/api')"
RESOLVED, exports: []

$ node -e "import('@hcs/kernel/src/policy/rule-resolution')"
BLOCKED by exports map: ERR_PACKAGE_PATH_NOT_EXPORTED

Node refuses the deep import before any CI gate has an opinion.

The test suite asserts the map publishes exactly two entry points, routes both through src/api/, and contains no wildcard and no src path — so a future PR cannot quietly widen it to make a convenient deep import work without turning the suite red.

Why the barrel is empty

Deliberate. This is the workspace scaffold, separated from the first service so that workspace wiring problems surface in a three-file diff rather than inside a six-hundred-line one.

The first service to land here is the read-only policy-snapshot loader, assigned by adr/0060 §Ring-1 policy/gateway loader, with its checkpoint-level test obligation specified by adr/0061 — reject at the digest-verification step, not merely at the final Decision. Both accepted; no new ADR required.

No justfile edit was needed

just test kernel works the moment this package has a tests/ directory, because #93 replaced the hardcoded case "$target" in ""|schemas) with discovery over packages/*/tests:

$ just test kernel
 ✓ packages/kernel/tests/api-surface.test.ts (5 tests) 5ms
   Test Files  1 passed (1)
        Tests  5 passed (5)

That was the stated payoff of the discovery change, and it holds. It also means this PR adds zero merge-collision surface on the justfile.

Boundary checks

  • No policy duplicated into adapter/hook
  • No universal shell execution added
  • No audit-write agent endpoint added
  • OperationShape remains upstream of CommandShape — none emitted
  • Registers no Capability; exposes no agent-callable surface; mints and consumes no ApprovalGrant
  • Adds no dependency (lockfile change is the workspace link only)
  • Ring 1 imports Ring 0 and nothing above it
  • Citation disciplineadr/0060 §Ring-1 policy/gateway loader and adr/0061's test obligation are cited as forward context, not as authorization for anything in this diff. This PR implements no service.
  • Precedence — amends no ADR, relieves no ADR-stated rule

Validation

just verify — green. just test kernel — 5/5. Deep-import block verified on this host, output above.

First non-.gitkeep file in Ring 1. packages/kernel has held an empty marker
since the repo was scaffolded.

Three files: a package manifest, an empty public-API barrel, and a test suite
that guards the ring boundary.

THE EXPORTS MAP IS THE POINT

charter §Package boundary enforcement:

  "packages/adapters/** cannot import from packages/kernel/src/** except
   through the declared public API surface (packages/kernel/src/api/)."

That rule now has two independent enforcers:

  1. scripts/ci/boundary-check.sh rule 2 — a grep. It went three months
     without executing once: a PCRE lookahead under `grep -E` exited rc=2 and
     `2>/dev/null` ate the diagnostic, so it printed "ring boundaries intact"
     while a planted violation passed. Repaired in #93.
  2. This package's `exports` map, which publishes `.` and `./api` and nothing
     else.

The second is the durable one. A grep can regress silently; a missing exports
entry cannot. Verified on this host:

  $ node -e "import('@hcs/kernel/api')"
    RESOLVED, exports: []
  $ node -e "import('@hcs/kernel/src/policy/rule-resolution')"
    BLOCKED by exports map: ERR_PACKAGE_PATH_NOT_EXPORTED

Node refuses the deep import before any CI gate has an opinion. The test suite
asserts the map publishes exactly two entry points, routes both through
src/api/, and contains no wildcard or `src` path — so a future PR cannot widen
it to make a convenient import work without turning the suite red.

WHY THE BARREL IS EMPTY

Deliberate. This is the workspace scaffold, and it is separated from the first
service so that workspace wiring problems surface in a three-file diff rather
than inside a six-hundred-line one.

The first service to land here is the read-only policy-snapshot loader,
assigned by ADR 0060 §Ring-1 policy/gateway loader, with its checkpoint-level
test obligation specified by ADR 0061 — reject at the digest-verification step,
not merely at the final Decision. Both are accepted; no new ADR is required.

NO JUSTFILE EDIT WAS NEEDED

`just test kernel` works the moment this package has a tests/ directory,
because #93 replaced the hardcoded `case "$target" in ""|schemas)` with
discovery over packages/*/tests. Confirmed:

  $ just test kernel
    ✓ packages/kernel/tests/api-surface.test.ts (5 tests)
    Test Files  1 passed (1)

That was the stated payoff of the discovery change and it holds. It also means
this PR adds zero merge-collision surface on the justfile.

Class D — kernel, read path. Registers no capability, exposes no agent-callable
surface, emits no OperationShape, mints and consumes no ApprovalGrant, adds no
dependency.

Validation: `just verify` green. `just test kernel` 5/5.
@verlyn13
verlyn13 requested a review from a team as a code owner July 25, 2026 19:08
@verlyn13
verlyn13 merged commit 160879c into main Jul 25, 2026
1 check passed
@verlyn13
verlyn13 deleted the feat/kernel-workspace-scaffold branch July 25, 2026 19:30
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