83 lines
5.0 KiB
Markdown
83 lines
5.0 KiB
Markdown
# Fixed local node-key effect
|
|
|
|
Status: local primitive implemented and unit-tested; **OP-M4 remains open**.
|
|
No runtime/REST/MCP/operator-window caller is connected to this primitive.
|
|
|
|
`createBandwidthNodeKeyEffect` captures a server-configured absolute key path,
|
|
public bootstrap, original deadline, actor signal and physical-owner signal.
|
|
Construction performs no filesystem I/O. Calls cannot renew its wall or
|
|
monotonic horizon, capped at five seconds from construction. These inputs are
|
|
configuration, **not proof of current authority, a signed bootstrap or Q**.
|
|
Proxy signals and all own signal accessors, including symbol properties, are
|
|
rejected before the initial native getter. Cancellation thereafter uses private
|
|
flags set by captured native EventTarget listeners; no signal getter or listener
|
|
operation runs under the loaded key. The caller must close the effect on every
|
|
terminal path to detach listeners, including when it never calculates again.
|
|
|
|
The fixed `calculate` operation captures at most four plain proof inputs using
|
|
the same schemas and canonical domains as the existing strong node source. It
|
|
rejects accessors, proxies, serializers, foreign roots and external domains on
|
|
v1 before touching the key. There is no caller function, arbitrary MAC text,
|
|
query handle, key return value or asynchronous result.
|
|
|
|
The operation checks canonical regular-file identity, pins the parent directory
|
|
device/inode across its phases, opens with NOFOLLOW/NONBLOCK where supported,
|
|
reads exactly 32 bytes, and checks the opened inode and pathname again. The
|
|
current key hash must equal the bootstrap pin. Key read, hash validation and
|
|
all HMACs occur without `await`. All actual scratch buffers are wiped before
|
|
descriptor closure. Actor/owner cancellation or expiration at closure still
|
|
suppresses the return value. Any error permanently refuses later calls; there
|
|
is no replay or key fallback. Native filesystem errors are sanitized.
|
|
|
|
This is deliberately not a replacement for the existing strong source guards.
|
|
That path shares only the pure input schemas/capture with this primitive; its
|
|
file ordering, ownership checks and Q guards remain in place. The new primitive
|
|
does not fix that path's asynchronous key lifetime or reduce its scan count.
|
|
|
|
## Limits and integration requirements
|
|
|
|
Only a local regular key is supported. A synchronous filesystem syscall can
|
|
block the event loop and cannot be preempted. Checks reject a late result after
|
|
the syscall returns; they do not guarantee OS latency. No additional thread,
|
|
process, pool or RAM allocation profile is introduced.
|
|
|
|
Before integration, the closed dispatcher must authenticate the current public
|
|
bootstrap/source and actor, confirm the original physical SQL owner and run
|
|
fresh Q immediately before the effect. Its post-effect Q must finish before
|
|
using the private MACs. A public bootstrap or the returned strings cannot mint
|
|
an effect permit. A lost physical-owner event that has not yet reached the
|
|
event loop is not prevented by reading an AbortSignal synchronously.
|
|
|
|
The claim MAC and snapshot-dependent MACs remain two distinct calls with no
|
|
key retained across the awaited locked snapshot. Sharing adjacent Q boundaries
|
|
still requires the complete private continuation and actual transport/SQL
|
|
dispatch proof described in the effect ledger. No measured-latency positive,
|
|
same-owner fixed transaction or real backend window is accepted by these tests.
|
|
|
|
The next integration needs an internal bridge in the core source, where the
|
|
actual raw lease is still available. The existing public lease must remain
|
|
exactly `inspect`/`close`. A private WeakMap can associate that genuine lease
|
|
with its owner state, then bind it once to a genuine original-window
|
|
continuation. The controller may expose only fixed `begin`, `lockedSnapshot`,
|
|
`applyEnrollment`, `commit`, `close` operations to its private composition;
|
|
arbitrary SQL, rows, MACs or validators supplied by a caller are excluded.
|
|
|
|
The intended state chain is HELD → BEGIN_ACK → SNAPSHOT_LOCKED →
|
|
VERIFIED_EXISTING or DO_ACK → COMMIT_STARTED → COMMIT_ACK → FINAL_CONFIRMED →
|
|
CLOSED. Private snapshot/plan capabilities must bind the exact transaction,
|
|
peer, root and original authority. From COMMIT_STARTED onward, lost ACK,
|
|
owner or authority means UNKNOWN, with no success publication, rollback claim
|
|
or automatic replay. Opening another public lease beside the current strong
|
|
window cannot establish a single physical owner. This is an integration
|
|
recommendation, not implemented code or an accepted latency proof.
|
|
|
|
## Verification
|
|
|
|
`npm --prefix backend run test:bandwidth-node-key-effect` covers actual local
|
|
files/crypto and the existing strong batch path. Filesystem observers inject
|
|
owner/actor loss, key replacement, deadline expiry, short reads and close
|
|
failure. The directory-clone test uses a real rename and replacement directory.
|
|
Windows without symlink privilege uses a synthetic `lstat` branch for the
|
|
symlink refusal case; it does not establish an actual Windows symlink race.
|
|
No PostgreSQL, Docker or real RouterOS target is involved in this profile.
|