@frockbot/workspace-store 0.0.0 → 0.1.0

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@frockbot/workspace-store",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./bucket": "./src/bucket.ts",
+    "./keys": "./src/keys.ts",
+    "./testing": "./src/testing.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-contracts": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@types/node": "26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/workspace-store"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/bucket.ts

@@ -0,0 +1,80 @@
+// The object store this package writes through, declared structurally.
+//
+// It is deliberately not `R2Bucket`. "Electron, Cloudflare, provider SDK, and
+// Computer implementation types remain inside their adapters" — so the store
+// consumes the four operations and the two conditional headers it actually
+// needs, an adapter in the Cloudflare app supplies them over R2, and a Bun
+// test supplies them over a Map. The two behave the same because this file,
+// not R2, is the contract.
+//
+// Conditional semantics are the whole point of the interface. ADR 0013 names
+// "object storage conditional writes (`If-Match` on the object's ETag)" as the
+// mechanism by which a write that has not seen the current generation loses
+// rather than overwrites, so `put` must be able to fail a precondition and say
+// so as a value.
+
+/** An object's metadata, without its bytes. */
+export interface ObjectHeadV1 {
+  key: string;
+  /** The entity tag an `If-Match` write is conditioned on. */
+  etag: string;
+  size: number;
+  /** When the store accepted these bytes; orders an unrecorded object. */
+  uploaded: Date;
+  /** Small opaque strings stored beside the bytes. */
+  customMetadata?: Record<string, string>;
+}
+
+/** An object with its bytes. */
+export interface ObjectBodyV1 extends ObjectHeadV1 {
+  bytes(): Promise<Uint8Array>;
+}
+
+/**
+ * The two conditions this store uses, and no others.
+ *
+ * `etagMatches` is `If-Match`: replace exactly the bytes the writer has seen.
+ * `etagDoesNotMatch: "*"` is `If-None-Match: *`: create only if absent, which
+ * is what `expectedGenerationId: null` asserts.
+ */
+export interface ObjectConditionsV1 {
+  etagMatches?: string;
+  etagDoesNotMatch?: string;
+}
+
+export interface ObjectPutOptionsV1 {
+  onlyIf?: ObjectConditionsV1;
+  customMetadata?: Record<string, string>;
+  contentType?: string;
+}
+
+export interface ObjectListRequestV1 {
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ObjectListPageV1 {
+  objects: ObjectHeadV1[];
+  truncated: boolean;
+  cursor?: string;
+}
+
+/**
+ * The minimal object store. Every method may reject; the store above turns a
+ * rejection into the declared `unavailable` variant rather than letting it
+ * escape, because object storage being briefly unreachable is an ordinary
+ * answer, not a failed Turn.
+ */
+export interface ObjectBucketV1 {
+  get(key: string): Promise<ObjectBodyV1 | null>;
+  head(key: string): Promise<ObjectHeadV1 | null>;
+  /** Answers `null` when a precondition in `options.onlyIf` failed. */
+  put(
+    key: string,
+    bytes: Uint8Array,
+    options?: ObjectPutOptionsV1,
+  ): Promise<ObjectHeadV1 | null>;
+  delete(key: string): Promise<void>;
+  list(request: ObjectListRequestV1): Promise<ObjectListPageV1>;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./bucket.js";
+export * from "./keys.js";
+export * from "./store.js";

package/src/keys.ts

@@ -0,0 +1,64 @@
+// Where a durable-root file lives in object storage, and where its losing
+// writes are preserved.
+//
+// One scheme, in one place, because three things must agree on it: this
+// package, the Computer-side sync agent of ADR 0013, and anything that reads
+// the bucket to rebuild an index.
+//
+//   file      workspace/<workspaceRootKeyV1(root)>/<relative>
+//   conflict  workspace/<workspaceRootKeyV1(root)>/<relative>.conflict/<generationId>
+//
+// The conflict key is a *prefix* of nothing a file can occupy, and that is
+// enforced rather than assumed: `normalizeWorkspaceRelativePathV1` refuses any
+// segment ending in `.conflict`, so `notes.conflict/a.md` is not a path a
+// caller can present. Listing a root therefore skips any key containing
+// `/<name>.conflict/`, and a preserved losing write is durable, addressable,
+// and never mistaken for the file it lost to.
+import {
+  WORKSPACE_CONFLICT_SEGMENT_SUFFIX,
+  workspaceRootKeyV1,
+  type WorkspaceRootV1,
+} from "@frockbot/kernel-contracts";
+
+/** Every durable-root object lives under this prefix. */
+export const WORKSPACE_OBJECT_PREFIX = "workspace";
+/** The segment marking a preserved losing write; a path may not end in it. */
+export const WORKSPACE_CONFLICT_SUFFIX = WORKSPACE_CONFLICT_SEGMENT_SUFFIX;
+
+/** The prefix every object of one durable root shares. */
+export function workspaceObjectPrefixV1(root: WorkspaceRootV1): string {
+  return `${WORKSPACE_OBJECT_PREFIX}/${workspaceRootKeyV1(root)}/`;
+}
+
+/** The object key holding one file's current bytes. */
+export function workspaceObjectKeyV1(
+  root: WorkspaceRootV1,
+  path: string,
+): string {
+  return `${workspaceObjectPrefixV1(root)}${path}`;
+}
+
+/** The object key preserving one losing write. */
+export function workspaceConflictKeyV1(
+  root: WorkspaceRootV1,
+  path: string,
+  generationId: string,
+): string {
+  return `${workspaceObjectKeyV1(root, path)}${WORKSPACE_CONFLICT_SUFFIX}/${generationId}`;
+}
+
+/** True for a key that preserves a losing write rather than holding a file. */
+export function isWorkspaceConflictKeyV1(key: string): boolean {
+  return key.includes(`${WORKSPACE_CONFLICT_SUFFIX}/`);
+}
+
+/** The relative path a file key names inside its root, if it names one. */
+export function workspaceRelativeFromKeyV1(
+  root: WorkspaceRootV1,
+  key: string,
+): string | undefined {
+  const prefix = workspaceObjectPrefixV1(root);
+  if (!key.startsWith(prefix)) return undefined;
+  const relative = key.slice(prefix.length);
+  return relative.length > 0 ? relative : undefined;
+}