Teeth for a Path, and the Seam That Is Not an Import

Byte-Compare Is the Wrong Signal

The next track will build the drift check: strip the header, substitute the vars, compare the body, run it from the consumer's own suite. That check is the teeth of a copy. It is the wrong teeth for a path package, and using it anyway would produce a decorative green.

A path consumer does not hold a copy. It compiles the kit directory as that directory sits on disk. If the working tree is dirty — a type half-edited, a package manifest tweaked and not committed — the binary that ships is the dirty tree. A byte-compare against the kit's last commit would either fail constantly (the consumer has no copy to compare) or pass vacuously (there is nothing in the consumer to drift). Neither outcome is a check.

The teeth are therefore a clean-tree gate on the archive. Before a store build, assert that the package sources and the package manifest match the kit's committed tree. A dirty kit cannot ship. An override exists for a build that is not an upload, because a bench has to be allowed to compile an experiment; an upload must not. On success the log names the kit commit the binary carries, so a later reader can answer "which kit was this" without archaeology.

The Package Must Not Depend on a Leaf

The two mechanisms sit in one repository. The tempting bridge is an import: the package wants the pin helper, the pin helper already lives as a vendored leaf in five apps, so the package imports it. That rebuilds the graph bug from the other side. The leaf is still delivered file-to-file, at whatever commit each consumer last deployed, while the package compiles against whatever is in the kit tree today. You have invented a third, unnamed mechanism whose coherence nobody checks.

The seam is injection. A door that needs to verify a PIN holds a verifier it is given. The five apps that already vendor the pin helper construct that helper and pass it in. The package never sees the leaf. A compile-time availability check — "import this if the module is present" — is not a seam. It is a hidden dependency that compiles in the apps that happen to have vendored the leaf and fails, or silently degrades, in the ones that have not.

Where two mechanisms meet, inject; do not import. Importing across the split smuggles the file map's blindness into the package, or the package's recency into the leaves, and neither side's teeth can see the pair. The test is the same membership question one axis over: does this type need to know which delivery mechanism the other type came from? If it does, you have already crossed.

Whose Suite, Again

The next track's founding failure was a rule stated as a file path, which silently exempted the consumer that could not host that path. The package half has the same shape available: "the check lives in the kit's own suite." That would report a dirty tree to whoever happens to be looking at the kit, after the binary has already been archived from a consumer.

So the gate runs on the consumer's upload path — the moment the dirty tree would otherwise become a store build. Same assertion, different host. The requirement is not a filename. The requirement is that a dirty kit cannot become a shipped binary. How a given consumer hosts that assertion is its own suite's problem, exactly as a frontend-only app hosted the copy-check in a JavaScript runner rather than growing a backend to satisfy a path.

Code

Two teeth, two units, one seam that is not an import·text

COPY TEETH (next track)
  compare stripped body of dest against rendered source
  host: each consumer's own suite
  signal: this file drifted

PACKAGE TEETH
  compare CwkKit sources + package manifest against kit HEAD
  host: the consumer's upload / archive path
  signal: this binary would compile a dirty kit
  override: allowed for a bench build, refused for an upload
  on green: print the kit commit the binary carries

THE SEAM
  package side:
    protocol PINVerifier { func verify(...) async throws -> PIN }
    struct Door { let verifier: PINVerifier }

  leaf side (still vendored, still a copy):
    struct LeafPIN: PINVerifier { ... }

  consumer shim (the app's handful of lines):
    Door(verifier: LeafPIN())

  NOT A SEAM
    #if canImport(LeafPIN)
    // compiles where the leaf was vendored,
    // degrades where it was not,
    // and no check on either side names the pair
    #endif

Exercise

If your system has both copied files and a compiled shared unit (a local package, a workspace crate, a project reference), write the teeth of each and the seam between them. Then grep the compiled unit for imports of the copied files. Every hit is a hidden third mechanism. For one hit, rewrite it as an injected protocol.

Hint

The import is often hidden behind an availability check or a convenience initializer. Search for the copied module's type names inside the compiled unit, not just for import statements.

Byte-Compare Is the Wrong Signal

The Package Must Not Depend on a Leaf

Whose Suite, Again

Code

External links

Exercise

Progress

Comments 0