@superbee/core 0.2.0-pre.4 → 0.2.0-pre.41

package/dist/string-identity-agreement.js

@@ -0,0 +1,72 @@
+/**
+ * Agreement rows for the two string identity primitives core owns: {@link foldPath}
+ * (`path-fold.ts`) and {@link compareCodeUnits} (`code-unit-order.ts`). Every expected value was
+ * written from the definitions, not captured from running the code, so a host that imports or
+ * copies these rows checks its own implementation against the definition, not against core.
+ *
+ * Shipped as a data-only module (no imports) under `@superbee/core/string-identity-agreement`, so a
+ * host test can import the rows directly, and a host that cannot depend on core can copy the file
+ * and compare its bytes. Strings use `\u` escapes so no editor or checkout can renormalize them.
+ */
+export const PATH_FOLD_ROWS = Object.freeze([
+    { note: "hyphen is not a letter", input: "a-b", fold: "a-b" },
+    { note: "dot is not a letter", input: "a.b", fold: "a.b" },
+    { note: "underscore is not a letter", input: "a_b", fold: "a_b" },
+    { note: "digit is not a letter", input: "a2", fold: "a2" },
+    { note: "plain lowercase is fixed", input: "ab", fold: "ab" },
+    { note: "ASCII uppercase", input: "REFERENCES", fold: "references" },
+    { note: "ASCII lowercase", input: "references", fold: "references" },
+    { note: "mixed case", input: "References", fold: "references" },
+    { note: "long s uppercases to S", input: "reference\u017F", fold: "references" },
+    { note: "long s inside a word", input: "re\u017Fource", fold: "resource" },
+    { note: "Kelvin sign meets K", input: "\u212A", fold: "k" },
+    { note: "ASCII K", input: "K", fold: "k" },
+    { note: "dotless i uppercases to I", input: "\u0131", fold: "i" },
+    { note: "ASCII I", input: "I", fold: "i" },
+    { note: "dotted capital I keeps its dot", input: "\u0130", fold: "i\u0307" },
+    { note: "NFD e acute composes", input: "e\u0301", fold: "\u00E9" },
+    { note: "NFC e acute", input: "\u00E9", fold: "\u00E9" },
+    { note: "NFC capital E acute", input: "\u00C9", fold: "\u00E9" },
+    { note: "NFD capital E acute", input: "E\u0301", fold: "\u00E9" },
+    { note: "capital sharp s", input: "\u1E9E", fold: "ss" },
+    { note: "sharp s", input: "\u00DF", fold: "ss" },
+    { note: "fullwidth r is not compatibility folded", input: "\uFF52", fold: "\uFF52" },
+    { note: "emoji has no case", input: "\u{1F41D}", fold: "\u{1F41D}" },
+    { note: "astral capital Deseret long I", input: "\u{10400}", fold: "\u{10428}" },
+    { note: "slash is untouched across segments", input: "Notes/Reference\u017F/A-B", fold: "notes/references/a-b" },
+]);
+export const PATH_COLLISION_ROWS = Object.freeze([
+    { a: "REFERENCES", b: "references", collide: true },
+    { a: "reference\u017F", b: "references", collide: true },
+    { a: "\u212A", b: "k", collide: true },
+    { a: "\u0131", b: "i", collide: true },
+    { a: "e\u0301", b: "\u00E9", collide: true },
+    { a: "\u1E9E", b: "ss", collide: true },
+    { a: "\u0130", b: "i", collide: false },
+    { a: "a-b", b: "a_b", collide: false },
+    { a: "a.b", b: "ab", collide: false },
+    { a: "\uFF52", b: "r", collide: false },
+]);
+/**
+ * Strings in UTF-16 code unit order. The emoji (lead surrogate U+D83D) sorts before U+E000, which
+ * code point order and `localeCompare` would both place differently.
+ */
+export const CODE_UNIT_ORDER = Object.freeze([
+    "K",
+    "REFERENCES",
+    "a-b",
+    "a.b",
+    "a2",
+    "a_b",
+    "ab",
+    "e\u0301",
+    "i",
+    "references",
+    "referen\u017Fes",
+    "\u00E9",
+    "\u0131",
+    "\u212A",
+    "\u{1F41D}",
+    "\uE000",
+]);
+//# sourceMappingURL=string-identity-agreement.js.map

package/dist/string-identity-agreement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-identity-agreement.js","sourceRoot":"","sources":["../src/string-identity-agreement.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { BodyReplacePosture } from "./body-replace-guards.js";
 /**
  * Shared type shapes for the OKF store engine.
  *
@@ -5,7 +6,7 @@
  * here so the implementation modules can import them without a cycle, and are
  * re-exported verbatim from `index.ts` to keep the public contract stable.
  *
- * @see OKF spec — GoogleCloudPlatform/knowledge-catalog, `okf/SPEC.md`
+ * @see OKF spec — GoogleCloudPlatform/open-knowledge-format, `SPEC.md`
  * @packageDocumentation
  */
 /**
@@ -140,7 +141,8 @@ export interface ReadBlobResult {
 export interface VersionInfo {
     /** Opaque content-addressed version token for this revision. */
     version: Version;
-    /** Who wrote this revision. Defaults to a local identity when the write was unattributed. */
+    /** Who wrote this revision. History-keeping backends default at write time to a local identity.
+     * FilesystemBackend reports `unattributed` when document bytes carry no mutation attribution. */
     actor: string;
     /** ISO-8601 instant this revision was recorded. */
     timestamp: string;
@@ -155,6 +157,10 @@ export interface VersionInfo {
 }
 /** Options controlling a conditional / attributed {@link StorageBackend.write}. */
 export interface WriteOptions {
+    /** Explicit per-document replacement intent carried by RemoteBackend to the wire authority.
+     * Raw storage adapters ignore it; it grants no metadata/Kind policy bypass.
+     */
+    bodyReplace?: BodyReplacePosture;
     /**
      * Compare-and-swap guard. When set to a {@link Version} token, the write succeeds
      * ONLY if the backend's current version for `id` equals that token; otherwise it
@@ -247,6 +253,8 @@ export interface StorageCapabilities {
  * identity of the returned document even when the input document carries a different `id`.
  */
 export interface StorageBackend {
+    /** Optional exact-store cooperating-writer inventory comparison plus one concept write. */
+    readonly inventoryGuard?: import("./inventory-guard.js").InventoryGuard;
     /** Read + parse the concept document at `id`, with its version token. Rejects (ENOENT-shaped) if absent. */
     read(id: ConceptId): Promise<ReadResult>;
     /**
@@ -349,11 +357,16 @@ export interface StorageBackend {
      * a facet it chooses to honor. A backend that does not implement this method
      * (FilesystemBackend / MemoryBackend — both local to their data, where a head projection
      * saves nothing) is served by the engine's fallback (`list` +
-     * `readMany`, bodies read then dropped), which additionally honors the scan's
-     * malformed-doc resilience (`QueryOptions.onSkip`); the push-down path does not — a
-     * malformed doc fails the server-side scan, exactly as the wire `list` always has.
+     * `readMany`, bodies read then dropped). Both paths honor the scan's malformed-doc
+     * resilience: given `onSkip`, a backend reports each document it could not parse there and
+     * leaves it out; without it, a malformed document fails the scan.
      */
-    queryHeads?(filter?: QueryFilter): Promise<HeadResult[]>;
+    queryHeads?(filter?: QueryFilter, options?: {
+        onSkip?: (skip: {
+            id: ConceptId;
+            reason: string;
+        }) => void;
+    }): Promise<HeadResult[]>;
     /**
      * OPTIONAL capabilities self-declaration. `StorageBackend` carries
      * no capabilities descriptor by default, so a wire router that wants to report an adapter's
@@ -395,6 +408,23 @@ export interface QueryFilter {
      * (e.g. `tags: [a,b]`) matches on membership. A field the doc lacks never matches (empty set).
      */
     fields?: Record<string, string>;
+    /**
+     * Restrict to concepts whose `sources` list holds at least one entry carrying this identity
+     * (see {@link SourceIdentity}). A selector naming neither key imposes no constraint, like an
+     * empty `tags` list.
+     */
+    sources?: SourceIdentity;
+}
+/**
+ * An OKF `sources[]` identity: `resource` names the provider namespace and `id` the record within
+ * it. Each supplied key must equal the entry's own property of the same name by exact,
+ * case-sensitive string comparison: no trimming, URL normalization, or `String()` coercion. An
+ * entry that is not a mapping, or whose property is absent or not a string, never matches, and
+ * neither does a `sources` value that is not a list.
+ */
+export interface SourceIdentity {
+    resource?: string;
+    id?: string;
 }
 /** A single resolved outbound cross-link (a standard markdown link, never a wikilink). */
 export interface Link {
@@ -406,6 +436,11 @@ export interface Link {
     text: string;
     /** The raw target as written in the markdown, before resolution (e.g. `/a/b.md`, `./x.md`). */
     href: string;
+    /**
+     * Set only on a cross-bundle edge (`okf://<alias>/<path>.md`): the declared alias of the bundle
+     * `to` lives in. Absent on every local link, so local edge output is unchanged.
+     */
+    bundle?: string;
 }
 /**
  * Filter for {@link queryEdges} — the whole-bundle derived edge list, filtered. `from`/`to` each

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,12 +1,2 @@
-/**
- * Shared type shapes for the OKF store engine.
- *
- * These are the contract types originally sketched in `index.ts`; they are kept
- * here so the implementation modules can import them without a cycle, and are
- * re-exported verbatim from `index.ts` to keep the public contract stable.
- *
- * @see OKF spec — GoogleCloudPlatform/knowledge-catalog, `okf/SPEC.md`
- * @packageDocumentation
- */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/uncertain-write.d.ts

@@ -15,9 +15,13 @@
  * `sleep` used for the submission deadline and the delay between lookups; there is no
  * injectable clock, and a transport's own latency is real.
  */
+import type { BodyReplacePosture } from "./body-replace-guards.js";
 import type { Version } from "./types.js";
-/** The operation an intent performs. Only document writes exist today; the union is open. */
-export type OperationKind = "document.write" | (string & {});
+/**
+ * The operation an intent performs: a whole-document write, or `document.delete` (the document
+ * leaves at exactly the intent's base). The union is open.
+ */
+export type OperationKind = "document.write" | "document.delete" | (string & {});
 /**
  * The journal states of an intent. `unknown` is the primitive's own classification of an
  * exhausted attempt: the authority may or may not hold the write, and a later attempt begins
@@ -29,8 +33,21 @@ export interface OperationIntent {
     /** Durable request identity: minted once at record time, reused verbatim on every retry. */
     requestId: string;
     kind: OperationKind;
+    /** Explicit whole-document edit intent, captured durably with this request identity.
+     * Absent on legacy/automatic writes, which retain body-replacement protection.
+     */
+    readonly bodyReplace?: Readonly<BodyReplacePosture>;
     /** The target the operation applies to; a concept id for `document.write`. */
     target: string;
+    /**
+     * The tombstone a create acknowledges it re-creates: the id's latest deletion, as the
+     * authority named it. Set only by an explicit decision to re-create a deleted document (the
+     * caller's own observed delete, or `keep` on a "deleted remotely" conflict), and only on a
+     * create recorded after that decision; never inferred by a transport. An authority whose latest
+     * deletion of the id is another one refuses the create, and the refusal comes back as a
+     * conflict.
+     */
+    recreates?: Version;
     /** The shared version the local edit was made against, or `null` for a create. */
     base: Version | null;
     /** The content-addressed version of `content`. */
@@ -50,24 +67,109 @@ export interface OperationIntent {
 export type Outcome = {
     kind: "committed";
     version: Version;
-} | {
+}
+/**
+ * The shared head moved. `actual` is the version the authority serves now, or `null` when it
+ * serves none ("deleted remotely"). With `actual: null`, `tombstone` names the deletion the
+ * authority reported, when it reported one: the acknowledgement a deliberate re-create sends.
+ * It is never a version any read serves, so it is never a base or a remote version.
+ */
+ | {
     kind: "conflict";
     actual: Version | null;
-} | {
+    tombstone?: Version;
+}
+/**
+ * `executed` is present only on a refusal that is not the identity's recorded answer: `false`
+ * when this attempt was refused before it could execute (nothing was sent, or the authority
+ * refused it before dispatch), `"unknown"` when the authority's answer does not say. Such a
+ * refusal is evidence about this attempt only, never about an earlier delivery of the identity.
+ */
+ | {
     kind: "refused";
     code: string;
     message: string;
-} | {
+    executed?: false | "unknown";
+}
+/**
+ * `refusal` names the attempt-only refusal that ended the call, when one did: a resend refused
+ * before execution while an earlier delivery may still be held. The identity stays unknown;
+ * the refusal says why it could not be settled now (for example, access withdrawn).
+ */
+ | {
     kind: "unknown";
+    refusal?: {
+        code: string;
+        message: string;
+    };
 };
+/**
+ * A lookup's answer that the authority holds the identity without a result yet: a delivery of
+ * it was admitted and may still commit. Distinct from `null`, which says it was never admitted.
+ */
+export interface LookupPending {
+    kind: "pending";
+}
+/** The one {@link LookupPending} answer. */
+export declare const LOOKUP_PENDING: LookupPending;
 /** A transport to a shared authority that records outcomes by request identity. */
 export interface OperationTransport {
     /** Deliver the intent once; a repeated `requestId` must return the recorded outcome unchanged. */
     submit(intent: OperationIntent, options?: {
         signal?: AbortSignal;
     }): Promise<Outcome>;
-    /** The recorded outcome for `requestId`, or `null` when the authority never recorded it. */
-    lookup(requestId: string): Promise<Outcome | null>;
+    /**
+     * The recorded outcome for `requestId`; {@link LookupPending} when the authority holds it
+     * unanswered; or `null` when the authority never recorded it. A transport that cannot tell
+     * pending from absent answers `null` for both.
+     */
+    lookup(requestId: string): Promise<Outcome | LookupPending | null>;
+}
+/** Minimal classification for recorded-only delivery. A commit need not invent a new-head
+ * version (for example, an identified blob delete can carry its complete absence receipt). */
+export interface NonExecutedAttempt {
+    kind: "not-executed";
+    attempts: number;
+    details: unknown;
+}
+export type RecordedWriteOutcome = NonExecutedAttempt | {
+    kind: "committed";
+} | {
+    kind: "conflict";
+} | {
+    kind: "refused";
+    code: string;
+    message: string;
+} | {
+    kind: "unknown";
+};
+export type RecordedWriteIntent = Pick<OperationIntent, "requestId" | "kind" | "target" | "createdAt" | "attempts" | "state"> & {
+    /** Opt-in qualification; old no-prefix explicit callers retain their contract. */
+    notAppliedThrough?: number;
+};
+export interface RecordedWriteTransport<I extends RecordedWriteIntent, O extends RecordedWriteOutcome> {
+    submit(intent: I, options?: {
+        signal?: AbortSignal;
+    }): Promise<O>;
+    /** Null/absence is inconclusive and NEVER grants this path permission to submit. */
+    lookup(requestId: string): Promise<O | null>;
+}
+/** Explicit starts are for callers that own persistence, not proof minted by this primitive.
+ * submit-claimed requires a freshly successful durable in_flight CAS, held under the checkout
+ * lock, immediately before this call; its counted attempt is sent at most once. After reopening,
+ * or when that freshness cannot be established, use lookup. Replaying a stored claim is NOT a
+ * fresh CAS. Nor does a new CAS prove an earlier unclear delivery cannot still commit: those
+ * identities must use lookup. This function creates no ticket or journal persistence itself. */
+export type RecordedWriteOptions = Omit<UncertainWriteOptions, "settlement" | "maxSubmissions" | "earlierDeliveryUnclear"> & {
+    settlement: "recorded-only";
+    start: "submit-claimed" | "lookup";
+};
+export interface RecordedWriteResult<I extends RecordedWriteIntent, O extends RecordedWriteOutcome> {
+    intent: Omit<I, "attempts" | "state"> & Pick<RecordedWriteIntent, "attempts" | "state">;
+    outcome: O | {
+        kind: "unknown";
+    };
+    lookups: number;
 }
 /** Wait `ms`, resolving early and harmlessly when `signal` aborts. Injected by tests. */
 export type Sleep = (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -84,6 +186,20 @@ export interface UncertainWriteOptions {
     maxSubmissions?: number;
     /** Timer; defaults to a `setTimeout` sleep. */
     sleep?: Sleep;
+    /**
+     * Ends the call early once aborted: no further lookup or resubmission starts, the wait between
+     * lookups is cut short, and the outcome is `unknown` unless one was already known. Absent, the
+     * call runs every lookup and submission it is permitted.
+     */
+    signal?: AbortSignal;
+    /**
+     * The intent's earlier submission, made by an earlier call, ended without a definitive answer
+     * (its outcome was unknown, or the call stopped while it was in flight). A resubmission refused
+     * before execution is then `unknown`, as one after an unclear submission in this call is.
+     * Default false: an earlier submission answered with such a refusal (a paused intent requeued)
+     * may be resent and refused again definitively.
+     */
+    earlierDeliveryUnclear?: boolean;
 }
 export interface UncertainWriteResult {
     /** The intent with `attempts` and `state` advanced to reflect this call. */
@@ -92,12 +208,16 @@ export interface UncertainWriteResult {
     /** How many times `lookup` was called in this call. */
     lookups: number;
 }
-/** Refusal codes that mean the caller's authorization is gone rather than the content wrong. */
+/**
+ * Refusal codes that pause shared operations rather than say the content is wrong: the caller's
+ * authorization is gone, or a hosted sync quota (`REQUEST_CAPACITY_*`, one per scope the host
+ * names) is spent. Nothing is lost; the refused intents are requeued when the store resumes.
+ */
 export declare const AUTHORIZATION_REFUSAL_CODES: ReadonlySet<string>;
 /** True when a refusal reports lost permission, which pauses further shared operations. */
-export declare function isAuthorizationRefusal(outcome: Outcome): boolean;
+export declare function isAuthorizationRefusal(outcome: Outcome | RecordedWriteOutcome): boolean;
 /** The journal state an outcome settles an intent into. */
-export declare function stateForOutcome(outcome: Outcome): OperationState;
+export declare function stateForOutcome(outcome: Outcome | RecordedWriteOutcome): OperationState;
 /** The longest request identity the wire accepts as `Idempotency-Key`. */
 export declare const REQUEST_ID_MAX_LENGTH = 128;
 /**
@@ -116,10 +236,12 @@ export declare function mintRequestId(): string;
  * at that version. This is the wire's post-expiry compare-and-swap property: a committed write
  * whose acknowledgement was lost and whose recorded outcome expired from the authority's
  * retention window is resubmitted with its original `base`, which no longer matches, and the
- * authority answers a conflict against the version the client itself committed. The mapping
- * depends only on the outcome and the intent, so the primitive owns it and every consumer
- * settles such a write as acknowledged rather than presenting it as a concurrent edit. Every
- * other conflict, including one against an absent head (`actual: null`), is returned unchanged.
+ * authority answers a conflict against the version the client itself committed. If the head
+ * has meanwhile returned to `base` exactly, the premise matches and the resubmission is applied
+ * again instead (see {@link performUncertainWrite}). The mapping depends only on the outcome and
+ * the intent, so the primitive owns it and every consumer settles such a write as acknowledged
+ * rather than presenting it as a concurrent edit. Every other conflict, including one against
+ * an absent head (`actual: null`), is returned unchanged.
  */
 export declare function settleAgainstIntent(outcome: Outcome, intent: OperationIntent): Outcome;
 /**
@@ -127,9 +249,9 @@ export declare function settleAgainstIntent(outcome: Outcome, intent: OperationI
  *
  * Flow: when the intent has never been submitted, submit it; when it has (`attempts > 0`), or
  * when a submission's outcome is unknown, look the request identity up. A positive lookup
- * settles the intent. A `null` lookup proves the authority never recorded the request, so a
- * resubmission with the same `requestId` is the first delivery and is allowed, up to
- * `maxSubmissions`. A lookup that fails leaves the outcome unknown and the intent for a later
+ * settles the intent. A `null` lookup is taken as proof that the authority never recorded the
+ * request, so a resubmission with the same `requestId` is the first delivery and is allowed, up
+ * to `maxSubmissions`. A lookup that fails leaves the outcome unknown and the intent for a later
  * call.
  *
  * No resubmission happens without a `null` lookup because a blind retry after an unknown
@@ -137,8 +259,26 @@ export declare function settleAgainstIntent(outcome: Outcome, intent: OperationI
  * twice, and even on one with it the retry can only ever learn what the lookup already knew.
  * The lookup is what turns "unknown" into a fact before any second delivery.
  *
+ * That fact is only as good as the transport's `null`. An authority that has expired or lost a
+ * record answers as if it never recorded it, and the reference wire transport returns `null`
+ * then. The resubmission is guarded only by its `base`, and versions are content hashes: if the
+ * write had landed and a third party has since restored `base` exactly, the premise matches, the
+ * write is applied a second time over that revert, and the outcome is `committed`. The hosted
+ * transport never answers `null` for an absent record once the intent is older than the host's
+ * stated retention window, less a skew margin, so it does not resubmit there.
+ *
+ * A refusal before execution ({@link isAuthorizationRefusal}) of a resubmission that follows an
+ * unclear submission (in this call, or an earlier one per `earlierDeliveryUnclear`) is `unknown`,
+ * carrying that refusal, not settled: a `null` lookup cannot prove an earlier delivery will not
+ * still arrive, and the delivery can still commit. After a {@link LookupPending} answer, which
+ * says a delivery is held, the same holds for every refusal the transport marks `executed`
+ * (a gateway's `400` included). A pending lookup still permits the resubmission.
+ *
  * By default every outcome passes through {@link settleAgainstIntent}, so a conflict naming the
  * intent's own version is committed. `recorded-only` preserves the recorded outcome instead.
  */
+export declare function performUncertainWrite<I extends RecordedWriteIntent, O extends RecordedWriteOutcome>(transport: RecordedWriteTransport<I, O>, intent: I, options: RecordedWriteOptions): Promise<RecordedWriteResult<I, O>>;
+/** Compatibility path: a complete document intent, with the existing counters/resubmission
+ * defaults. Body delivery's recorded-only call without start remains on this path. */
 export declare function performUncertainWrite(transport: OperationTransport, intent: OperationIntent, options?: UncertainWriteOptions): Promise<UncertainWriteResult>;
 //# sourceMappingURL=uncertain-write.d.ts.map

package/dist/uncertain-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uncertain-write.d.ts","sourceRoot":"","sources":["../src/uncertain-write.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"uncertain-write.d.ts","sourceRoot":"","sources":["../src/uncertain-write.ts"],"names":[],"mappings":"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"}