@ai-slot/operations 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iannil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @ai-slot/operations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** | [简体中文](https://github.com/iannil/ai-slot-component/blob/master/packages/operations/README.zh-CN.md)
+
+An experimental public server-side package that provides version-state validation and a local single-writer file store. The 0.x API and persisted format do not yet guarantee compatibility across versions. Requires Node.js 22 or later. `openFileStore(directory)` maintains `state.json` and an exclusive `writer.lock` in the directory. Transactions commit drafts, approvals, publication records, pointers, and idempotency receipts as a single snapshot. The current limits are 64 MiB and 1,000 publication records. Only local filesystems with atomic rename semantics are supported; NFS, cloud-synced directories, and multiple service instances are not supported.
+
+## Installation
+
+```bash
+npm install @ai-slot/operations
+```
+
+Import `openFileStore` and `createOperations`; the workflow is described below. A complete runnable reference service is available at [`examples/managed-slot`](https://github.com/iannil/ai-slot-component/tree/master/examples/managed-slot).
+
+## Transactions and manual recovery
+
+Transactions execute in call order, and reads enter the same queue. A commit first validates all references, then writes a temporary file in the same directory, syncs the file, renames it to `state.json`, and finally syncs the directory. A failure at `beforeRename` leaves the previous snapshot unchanged. A failure after rename returns `commit_unknown`, and the handle stops accepting further writes. Callers should check the idempotency receipt to determine the commit outcome, rather than treating this error as a definitive failure and retrying blindly.
+
+1. Stop the sole service and back up the entire storage directory, including `state.json`, temporary files, and `writer.lock`.
+2. Check the PID and random nonce in `writer.lock` and confirm that the original service process has exited. Do not automatically take over a lock based on its age.
+3. Have an administrator manually move the leftover `writer.lock` out of the directory, then call `openFileStore` again. Startup checks the snapshot size before parsing and uses `assertState` to validate the structure, hashes, and all references. A corrupt snapshot prevents startup; it is never reset to an empty store.
+4. Look up the corresponding receipt using the idempotency key to confirm whether the publication was persisted before deciding on the next business action.
+
+The `fault` injection option is for fault testing only, not application configuration.
+
+## Drafts, publication, and public delivery
+
+`createOperations(store, env)` is the unified entry point for governance and delivery. `listSlots(actor)` lists only slots with a policy for which the actor has `read` permission. `readSlot(actor, slotId)` returns only that slot's publication pointer and drafts. `previewDraft` and `getStatus` also require `read` permission for the slot. Draft creation validates the tree, source, and live baseline, then stores the content as an immutable artifact addressed by SHA-256. The preview's `previous` is pinned to the version at draft creation. Approval rechecks the hash, baseline, source, and component contract. Approval validity is limited to 15 minutes and must not extend beyond the source's expiry.
+
+A complete workflow follows. Both publication and rollback require the approver to review the content hash and expiry again:
+
+1. `createDraft(actor, { slotId, tree, baseRevision, sourceVersion })` creates a draft.
+2. `previewDraft(actor, draft.id)` shows the draft, artifact hash, and differences from the baseline.
+3. `approveDraft(actor, { draftId, artifactHash, expiresAt })` approves the draft.
+4. `publishDraft(actor, { draftId, artifactHash, expectedRevision, idempotencyKey })` publishes atomically and returns a receipt for the new revision.
+5. `deliver(slotId)` publicly delivers the current version. It accepts no administrator identity and returns no drafts, approver information, or source credentials.
+6. To roll back, `prepareRollback(actor, { slotId, targetRevision, expectedRevision })` creates a new rollback draft from a historical artifact.
+7. Run `previewDraft` and `approveDraft` again to review the rollback draft.
+8. `rollbackSlot(actor, { draftId, artifactHash, expectedRevision, idempotencyKey })` publishes a new revision rather than moving the pointer back to an old revision number.
+
+`deliver` returns version 1 JSON: `{ version, slot, tree, meta: { revision, artifactHash, sourceVersion, expiresAt } }`. `expiresAt` is the Unix timestamp in milliseconds stored in the artifact. All responses use `Cache-Control: no-store`. A known slot with no readable published content, or whose current source, component contract, or expiry fails validation, returns `503 { "error": "ai_unavailable" }`, allowing the page to retain its original content. Unknown slots return 404. Exceptions thrown while reading the source are normalized to `source_unavailable`; invalid source data still produces `source_invalid`. Public responses do not expose these internal details.
+
+`getStatus(actor, slotId)` returns `{ desiredRevision, readableRevision, browserObservation }`. `desiredRevision` comes from the publication pointer and is retained even when the current source becomes invalid. `readableRevision` is populated only if the same live readability checks pass. `browserObservation` is always `null` because the server has no observation of browser rendering. Every delivery rereads the external source. An external source and a file transaction cannot be locked atomically across systems, so this package does not guarantee that the source remains unchanged after validation. This is a single-site reference implementation; it does not provide arbitrary factual or semantic verification, or automatic approval of financial promotions.
+
+## Validation status and scope
+
+This package does not start an HTTP service automatically or provide support for multiple instances or tenant isolation. Protocol and scripted validation have passed; validation with real operators and customer pilots has not yet been completed. Back up state before upgrading. Automatic migration of historical experimental snapshots is not guaranteed.

package/README.zh-CN.md

@@ -0,0 +1,43 @@
+# @ai-slot/operations
+
+[English](https://github.com/iannil/ai-slot-component/blob/master/packages/operations/README.md) | **简体中文**
+
+实验性服务端公开包（0.x API 和持久格式尚不承诺跨版本兼容），提供版本状态校验与本地单写者文件库。需要 Node.js 22 或更新版本。`openFileStore(directory)` 在目录中维护 `state.json` 和独占的 `writer.lock`，事务把草稿、审批、发布记录、指针及幂等回执作为一个快照提交。当前边界为 64 MiB 和 1000 条发布记录；只支持本地具备原子 rename 语义的文件系统，不支持 NFS、云同步目录或多个服务实例。
+
+事务按调用顺序执行，读取也进入同一队列。提交先校验完整引用关系，再写同目录临时文件、同步文件、rename 到 `state.json`，最后同步目录。`beforeRename` 失败不会改变旧快照；rename 后失败返回 `commit_unknown`，该句柄停止后续写入。调用方应通过幂等回执核对提交结果，不能把该错误视为明确失败并盲目重试。
+
+## 人工恢复
+
+1. 停止唯一服务，备份整个存储目录（包括 `state.json`、临时文件及 `writer.lock`）。
+2. 核对 `writer.lock` 中的 PID 与随机 nonce，并确认原服务进程确已退出；不要按锁文件年龄自动抢占。
+3. 管理员人工移走残留的 `writer.lock`，重新调用 `openFileStore`。启动会在解析前检查快照大小，并用 `assertState` 校验结构、hash 和所有引用；损坏快照会拒绝启动，不会重置为空库。
+4. 用幂等键查询对应回执确认发布是否已经落盘，再决定后续业务动作。
+
+`fault` 注入选项只供故障测试使用，不是业务配置。
+
+## 草稿、发布与公开投递
+
+`createOperations(store, env)` 是治理和交付的统一入口。`listSlots(actor)` 只列出有 `read` 授权且存在策略的槽位；`readSlot(actor, slotId)` 只返回该槽位的发布指针与草稿。`previewDraft` 和 `getStatus` 同样需要本槽位的 `read` 授权。草稿建立时校验树、来源与线上基线，将内容写成以 SHA-256 寻址的不可变 artifact；预览的 `previous` 固定到草稿创建时的版本。批准再次核对哈希、基线、来源及组件契约，且有效期最多 15 分钟并不得超过来源期限。
+
+一次完整的操作顺序如下，其中发布和回滚都需要批准人重新审核内容哈希与有效期：
+
+1. `createDraft(actor, { slotId, tree, baseRevision, sourceVersion })` 建立草稿。
+2. `previewDraft(actor, draft.id)` 查看草稿、artifact 哈希和基线差异。
+3. `approveDraft(actor, { draftId, artifactHash, expiresAt })` 批准该草稿。
+4. `publishDraft(actor, { draftId, artifactHash, expectedRevision, idempotencyKey })` 原子发布，并取得新 revision 回执。
+5. `deliver(slotId)` 公开交付当前版本；它不接受管理员身份，也不会返回草稿、批准人或来源凭据。
+6. 需要回滚时，`prepareRollback(actor, { slotId, targetRevision, expectedRevision })` 将历史 artifact 建成新的回滚草稿。
+7. 再次 `previewDraft` 和 `approveDraft`，审核这份回滚草稿。
+8. `rollbackSlot(actor, { draftId, artifactHash, expectedRevision, idempotencyKey })` 发布新的 revision，而非移动指针回旧编号。
+
+`deliver` 返回版本 1 的 JSON：`{ version, slot, tree, meta: { revision, artifactHash, sourceVersion, expiresAt } }`。`expiresAt` 是 artifact 中的 Unix 毫秒时间。所有响应均使用 `Cache-Control: no-store`。已知槽位没有可读发布内容，或当前来源、组件契约、有效期校验失败时，返回 `503 { "error": "ai_unavailable" }`，由页面保留原始内容；未知槽位返回 404。来源读取抛出的异常会统一转成 `source_unavailable`，来源数据本身不合法仍是 `source_invalid`，公开响应不会暴露这些内部细节。
+
+`getStatus(actor, slotId)` 返回 `{ desiredRevision, readableRevision, browserObservation }`。`desiredRevision` 来自发布指针，即使当前来源失效也保留；`readableRevision` 只有通过同一实时可读性检查才有值；`browserObservation` 固定为 `null`，因为服务端没有浏览器渲染观测。每次交付都会重读外部来源，外部来源与文件事务不能跨系统原子锁定，因此不承诺来源在校验后永不变化。此包是单站点参考实现，不负责任意事实语义验证或金融促销自动审批。
+
+## 安装与验收边界
+
+```bash
+npm install @ai-slot/operations
+```
+
+可导入 `openFileStore`、`createOperations`，调用流程见上文。完整可运行参考服务位于仓库 `examples/managed-slot`；此包不自动启动 HTTP 服务，也不提供多实例或租户隔离。协议和脚本验收已通过，真实运营人员及客户试点尚未完成。升级前备份状态；不承诺自动迁移历史试验快照。

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+import { ComponentNode, Registry } from '@ai-slot/registry';
+
+type Action = 'read' | 'draft' | 'approve' | 'publish' | 'rollback';
+interface Principal {
+    id: string;
+    grants: Record<string, Action[]>;
+}
+interface Source {
+    id: string;
+    version: string;
+    expiresAt: number;
+    data: Record<string, unknown>;
+}
+interface SlotPolicy {
+    slotId: string;
+    registryVersion: string;
+    rendererVersion: string;
+    sourceId: string;
+    allowedComponents: string[];
+    lockedProps: {
+        component: string;
+        prop: string;
+        sourceField: string;
+    }[];
+    urlProps: {
+        component: string;
+        prop: string;
+    }[];
+    allowedOrigins: string[];
+}
+interface Artifact {
+    hash: string;
+    slotId: string;
+    tree: ComponentNode;
+    sourceId: string;
+    sourceVersion: string;
+    registryVersion: string;
+    rendererVersion: string;
+    expiresAt: number;
+}
+interface Draft {
+    id: string;
+    artifactHash: string;
+    slotId: string;
+    baseRevision: number;
+    createdBy: string;
+    intent: 'publish' | 'rollback';
+    createdAt: number;
+}
+interface Approval {
+    draftId: string;
+    artifactHash: string;
+    baseRevision: number;
+    approvedBy: string;
+    expiresAt: number;
+}
+interface Release {
+    slotId: string;
+    revision: number;
+    artifactHash: string;
+    draftId: string;
+    actor: string;
+    action: 'publish' | 'rollback';
+    at: number;
+}
+interface Receipt {
+    revision: number;
+    artifactHash: string;
+    slotId: string;
+}
+interface State {
+    format: 1;
+    artifacts: Record<string, Artifact>;
+    drafts: Record<string, Draft>;
+    approvals: Record<string, Approval>;
+    releases: Release[];
+    pointers: Record<string, Receipt>;
+    idempotency: Record<string, {
+        fingerprint: string;
+        receipt: Receipt;
+    }>;
+}
+interface Store {
+    read(): Promise<State>;
+    transact<T>(change: (state: State) => T | Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+interface Environment {
+    registry: Registry;
+    policies: Record<string, SlotPolicy>;
+    readSource: (slotId: string) => Promise<Source>;
+    now: () => number;
+    notify: (slotId: string) => void | Promise<void>;
+}
+declare class OperationError extends Error {
+    code: string;
+    constructor(code: string);
+}
+
+declare function canonical(value: unknown): string;
+declare const hash: (v: unknown) => string;
+
+declare function emptyState(): State;
+/** 启动和提交共同使用的完整结构及引用校验。 */
+declare function assertState(input: unknown): asserts input is State;
+
+type Phase = 'beforeRename' | 'afterRename';
+type Fault = (phase: Phase) => void;
+/** 单进程写者；锁残留必须由管理员核实后人工移走。 */
+declare function openFileStore(directory: string, fault?: Fault): Promise<Store>;
+
+/** 权限必须由调用者对该槽位显式授予。 */
+declare function authorize(actor: Principal, slotId: string, action: Action): void;
+/** 检查组件、来源事实和 URL；返回与调用方输入隔离的已验证快照。 */
+declare function validateArtifact(env: Environment, slotId: string, tree: unknown, source: Source): ComponentNode;
+
+interface DraftInput {
+    slotId: string;
+    tree: unknown;
+    baseRevision: number;
+    sourceVersion: string;
+}
+interface ApprovalInput {
+    draftId: string;
+    artifactHash: string;
+    expiresAt: number;
+}
+declare function readSource(env: Environment, slotId: string): Promise<Source>;
+/** 发布、批准和回滚共同使用当前契约与来源快照校验。 */
+declare function assertCurrentArtifact(env: Environment, artifact: Artifact): Promise<void>;
+/** 在单个事务中校验来源与基线，然后固定草稿及内容哈希。 */
+declare function createDraft(store: Store, env: Environment, actor: Principal, input: DraftInput): Promise<Draft>;
+/** 差异基线固定为草稿创建时的版本。 */
+declare function previewDraft(store: Store, _env: Environment, actor: Principal, draftId: string): Promise<{
+    draft: Draft;
+    artifact: Artifact;
+    previous: Artifact | null;
+}>;
+/** 批准前再次校验来源、组件契约和线上基线。 */
+declare function approveDraft(store: Store, env: Environment, actor: Principal, input: ApprovalInput): Promise<Approval>;
+interface RollbackInput {
+    slotId: string;
+    targetRevision: number;
+    expectedRevision: number;
+}
+/** 历史内容重新进入草稿和审批链；线上指针保持原状。 */
+declare function prepareRollback(store: Store, env: Environment, actor: Principal, input: RollbackInput): Promise<Draft>;
+
+interface PublishInput {
+    draftId: string;
+    artifactHash: string;
+    expectedRevision: number;
+    idempotencyKey: string;
+}
+/** 原子 CAS 发布；幂等命中前仍检查当前授权。 */
+declare function commitDraft(store: Store, env: Environment, actor: Principal, input: PublishInput, action: Extract<Action, 'publish' | 'rollback'>): Promise<Receipt>;
+
+/** 只交付当前活动版本；来源读取失败时不使用先前快照补位。 */
+declare function deliver(store: Store, env: Environment, slotId: string): Promise<Response>;
+/** desired来自发布指针；readable必须通过与公开投递相同的实时检查。 */
+declare function getStatus(store: Store, env: Environment, actor: Principal, slotId: string): Promise<{
+    desiredRevision: number;
+    readableRevision: number | null;
+    browserObservation: null;
+}>;
+
+/** 管理操作与公开投递的唯一入口。 */
+interface Operations {
+    listSlots(actor: Principal): Promise<string[]>;
+    readSlot(actor: Principal, slotId: string): Promise<{
+        pointer: Receipt | null;
+        drafts: Draft[];
+    }>;
+    createDraft(actor: Principal, input: DraftInput): Promise<Draft>;
+    previewDraft(actor: Principal, draftId: string): Promise<{
+        draft: Draft;
+        artifact: Artifact;
+        previous: Artifact | null;
+    }>;
+    approveDraft(actor: Principal, input: ApprovalInput): Promise<Approval>;
+    publishDraft(actor: Principal, input: PublishInput): Promise<Receipt>;
+    prepareRollback(actor: Principal, input: RollbackInput): Promise<Draft>;
+    rollbackSlot(actor: Principal, input: PublishInput): Promise<Receipt>;
+    getStatus(actor: Principal, slotId: string): Promise<{
+        desiredRevision: number;
+        readableRevision: number | null;
+        browserObservation: null;
+    }>;
+    deliver(slotId: string): Promise<Response>;
+}
+declare function createOperations(store: Store, env: Environment): Operations;
+
+export { type Action, type Approval, type ApprovalInput, type Artifact, type Draft, type DraftInput, type Environment, OperationError, type Operations, type Principal, type PublishInput, type Receipt, type Release, type RollbackInput, type SlotPolicy, type Source, type State, type Store, approveDraft, assertCurrentArtifact, assertState, authorize, canonical, commitDraft, createDraft, createOperations, deliver, emptyState, getStatus, hash, openFileStore, prepareRollback, previewDraft, readSource, validateArtifact };

package/dist/index.js

@@ -0,0 +1,688 @@
+// src/types.ts
+var OperationError = class extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+  code;
+};
+
+// src/canonical.ts
+import { createHash } from "crypto";
+function canonical(value) {
+  const active = /* @__PURE__ */ new Set();
+  function visit(v) {
+    if (v === null || typeof v === "string" || typeof v === "boolean") return JSON.stringify(v);
+    if (typeof v === "number" && Number.isFinite(v)) return JSON.stringify(v);
+    if (typeof v !== "object" || v === null) throw Error("non_json");
+    if (active.has(v)) throw Error("cycle");
+    if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) throw Error("non_plain");
+    active.add(v);
+    try {
+      if (Array.isArray(v)) return "[" + Array.from(v, (x) => visit(x)).join(",") + "]";
+      return "{" + Object.keys(v).sort().map((k) => JSON.stringify(k) + ":" + visit(v[k])).join(",") + "}";
+    } finally {
+      active.delete(v);
+    }
+  }
+  return visit(value);
+}
+var hash = (v) => createHash("sha256").update(canonical(v)).digest("hex");
+
+// src/state.ts
+var fail = () => {
+  throw new OperationError("corrupt_state");
+};
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+var own = (value, key) => Object.hasOwn(value, key) ? value[key] : void 0;
+var validString = (value) => typeof value === "string" && value.length > 0 && value.length <= 200;
+var validHash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+var revision = (value, minimum = 0) => Number.isSafeInteger(value) && value >= minimum;
+var time = (value) => typeof value === "number" && Number.isFinite(value);
+function requireString(value) {
+  if (!validString(value)) fail();
+}
+function requireHash(value) {
+  if (!validHash(value)) fail();
+}
+function requireRevision(value, minimum = 0) {
+  if (!revision(value, minimum)) fail();
+}
+function requireTime(value) {
+  if (!time(value)) fail();
+}
+function requireRecord(value) {
+  if (!record(value)) fail();
+}
+function requireEnum(value, allowed) {
+  if (!allowed.includes(value)) fail();
+}
+function json(value, active = /* @__PURE__ */ new Set(), depth = 0) {
+  if (depth > 256) fail();
+  if (typeof value === "string") return;
+  if (value === null || typeof value === "boolean" || time(value)) return;
+  if (typeof value !== "object" || value === null) fail();
+  const object = value;
+  if (active.has(object)) fail();
+  if (!Array.isArray(value) && !record(value)) fail();
+  active.add(object);
+  try {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        if (!Object.hasOwn(value, i)) fail();
+        json(value[i], active, depth + 1);
+      }
+    } else {
+      for (const [key, child] of Object.entries(object)) {
+        requireString(key);
+        json(child, active, depth + 1);
+      }
+    }
+  } finally {
+    active.delete(object);
+  }
+}
+function requireTree(value, depth = 0) {
+  if (depth > 256) fail();
+  requireRecord(value);
+  requireString(own(value, "component"));
+  const props = own(value, "props");
+  if (props !== void 0) requireRecord(props);
+  const children = own(value, "children");
+  if (children !== void 0) {
+    if (!Array.isArray(children)) fail();
+    for (const child of children) requireTree(child, depth + 1);
+  }
+  const slots = own(value, "slots");
+  if (slots !== void 0) {
+    requireRecord(slots);
+    for (const nodes of Object.values(slots)) {
+      if (!Array.isArray(nodes)) fail();
+      for (const child of nodes) requireTree(child, depth + 1);
+    }
+  }
+}
+function emptyState() {
+  return { format: 1, artifacts: {}, drafts: {}, approvals: {}, releases: [], pointers: {}, idempotency: {} };
+}
+function assertState(input) {
+  requireRecord(input);
+  if (own(input, "format") !== 1) fail();
+  for (const name of ["artifacts", "drafts", "approvals", "pointers", "idempotency"]) requireRecord(own(input, name));
+  const releases = own(input, "releases");
+  if (!Array.isArray(releases)) fail();
+  json(input);
+  const state = input;
+  if (state.releases.length > 1e3) throw new OperationError("storage_limit");
+  for (const [key, artifact] of Object.entries(state.artifacts)) {
+    requireHash(key);
+    requireRecord(artifact);
+    const stored = own(artifact, "hash");
+    requireHash(stored);
+    requireString(own(artifact, "slotId"));
+    requireTree(own(artifact, "tree"));
+    requireString(own(artifact, "sourceId"));
+    requireString(own(artifact, "sourceVersion"));
+    requireString(own(artifact, "registryVersion"));
+    requireString(own(artifact, "rendererVersion"));
+    requireTime(own(artifact, "expiresAt"));
+    const { hash: _, ...payload } = artifact;
+    if (key !== stored || stored !== hash(payload)) fail();
+  }
+  for (const [key, draft] of Object.entries(state.drafts)) {
+    requireString(key);
+    requireRecord(draft);
+    const id = own(draft, "id");
+    requireString(id);
+    const artifactHash = own(draft, "artifactHash");
+    requireHash(artifactHash);
+    const slotId = own(draft, "slotId");
+    requireString(slotId);
+    requireRevision(own(draft, "baseRevision"));
+    requireString(own(draft, "createdBy"));
+    requireEnum(own(draft, "intent"), ["publish", "rollback"]);
+    requireTime(own(draft, "createdAt"));
+    const artifact = Object.hasOwn(state.artifacts, artifactHash) ? state.artifacts[artifactHash] : void 0;
+    if (key !== id || !artifact || artifact.slotId !== slotId) fail();
+  }
+  for (const [key, approval] of Object.entries(state.approvals)) {
+    requireString(key);
+    requireRecord(approval);
+    const draftId = own(approval, "draftId");
+    requireString(draftId);
+    const artifactHash = own(approval, "artifactHash");
+    requireHash(artifactHash);
+    const baseRevision = own(approval, "baseRevision");
+    requireRevision(baseRevision);
+    requireString(own(approval, "approvedBy"));
+    requireTime(own(approval, "expiresAt"));
+    const draft = Object.hasOwn(state.drafts, draftId) ? state.drafts[draftId] : void 0;
+    if (key !== draftId || !draft || draft.artifactHash !== artifactHash || draft.baseRevision !== baseRevision) fail();
+  }
+  const last = /* @__PURE__ */ new Map();
+  for (const release of state.releases) {
+    requireRecord(release);
+    const slotId = own(release, "slotId");
+    requireString(slotId);
+    const currentRevision = own(release, "revision");
+    requireRevision(currentRevision, 1);
+    const artifactHash = own(release, "artifactHash");
+    requireHash(artifactHash);
+    const draftId = own(release, "draftId");
+    requireString(draftId);
+    requireString(own(release, "actor"));
+    requireEnum(own(release, "action"), ["publish", "rollback"]);
+    requireTime(own(release, "at"));
+    const draft = Object.hasOwn(state.drafts, draftId) ? state.drafts[draftId] : void 0;
+    const artifact = Object.hasOwn(state.artifacts, artifactHash) ? state.artifacts[artifactHash] : void 0;
+    if (!draft || !artifact || draft.slotId !== slotId || artifact.slotId !== slotId || draft.artifactHash !== artifactHash || draft.intent !== release.action) fail();
+    if (currentRevision !== (last.get(slotId)?.revision ?? 0) + 1) fail();
+    last.set(slotId, release);
+  }
+  for (const [slot, pointer] of Object.entries(state.pointers)) {
+    requireString(slot);
+    requireRecord(pointer);
+    const pointerSlot = own(pointer, "slotId");
+    requireString(pointerSlot);
+    const pointerRevision = own(pointer, "revision");
+    requireRevision(pointerRevision, 1);
+    const pointerHash = own(pointer, "artifactHash");
+    requireHash(pointerHash);
+    const release = last.get(slot);
+    if (!release || pointerSlot !== slot || pointerRevision !== release.revision || pointerHash !== release.artifactHash) fail();
+  }
+  if (last.size !== Object.keys(state.pointers).length) fail();
+  for (const [key, entry] of Object.entries(state.idempotency)) {
+    requireString(key);
+    requireRecord(entry);
+    requireHash(own(entry, "fingerprint"));
+    const receipt = own(entry, "receipt");
+    requireRecord(receipt);
+    const slotId = own(receipt, "slotId");
+    requireString(slotId);
+    const receiptRevision = own(receipt, "revision");
+    requireRevision(receiptRevision, 1);
+    const artifactHash = own(receipt, "artifactHash");
+    requireHash(artifactHash);
+    if (!state.releases.some((r) => r.slotId === slotId && r.revision === receiptRevision && r.artifactHash === artifactHash)) fail();
+  }
+}
+
+// src/file-store.ts
+import { randomUUID } from "crypto";
+import { mkdir, open, readFile, rename, rm } from "fs/promises";
+import { join } from "path";
+var MAX_BYTES = 64 * 1024 * 1024;
+async function readState(directory) {
+  const file = await open(join(directory, "state.json"), "r");
+  try {
+    if ((await file.stat()).size > MAX_BYTES) throw new OperationError("storage_limit");
+    const bytes = await file.readFile();
+    if (bytes.length > MAX_BYTES) throw new OperationError("storage_limit");
+    let state;
+    try {
+      state = JSON.parse(bytes.toString("utf8"));
+    } catch {
+      throw new OperationError("corrupt_state");
+    }
+    assertState(state);
+    return state;
+  } finally {
+    await file.close();
+  }
+}
+async function writeState(directory, state, fault) {
+  assertState(state);
+  const bytes = Buffer.from(canonical(state));
+  if (bytes.length > MAX_BYTES || state.releases.length > 1e3) throw new OperationError("storage_limit");
+  const temp = join(directory, `state-${randomUUID()}.tmp`);
+  let renamed = false;
+  try {
+    const file = await open(temp, "wx", 384);
+    try {
+      await file.writeFile(bytes);
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    fault?.("beforeRename");
+    await rename(temp, join(directory, "state.json"));
+    renamed = true;
+    fault?.("afterRename");
+    const dir = await open(directory, "r");
+    try {
+      await dir.sync();
+    } finally {
+      await dir.close();
+    }
+  } catch (error) {
+    if (renamed) throw new OperationError("commit_unknown");
+    throw error;
+  } finally {
+    try {
+      await rm(temp, { force: true });
+    } catch (error) {
+      if (renamed) throw new OperationError("commit_unknown");
+      throw error;
+    }
+  }
+}
+async function unlockOwned(lock, identity) {
+  try {
+    if (await readFile(lock, "utf8") === identity) await rm(lock);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+async function openFileStore(directory, fault) {
+  await mkdir(directory, { recursive: true, mode: 448 });
+  const lock = join(directory, "writer.lock");
+  const identity = `${process.pid}:${randomUUID()}`;
+  const handle = await open(lock, "wx", 384);
+  try {
+    await handle.writeFile(identity);
+    await handle.sync();
+    await handle.close();
+  } catch (error) {
+    await handle.close().catch(() => void 0);
+    await unlockOwned(lock, identity);
+    throw error;
+  }
+  try {
+    try {
+      await readState(directory);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      await writeState(directory, emptyState());
+    }
+  } catch (error) {
+    await unlockOwned(lock, identity);
+    throw error;
+  }
+  let tail = Promise.resolve();
+  let closed = false;
+  let poisoned = false;
+  function enqueue(work) {
+    const job = tail.then(work);
+    tail = job.then(() => void 0, () => void 0);
+    return job;
+  }
+  return {
+    read() {
+      if (closed) return Promise.reject(new OperationError("store_closed"));
+      return enqueue(async () => structuredClone(await readState(directory)));
+    },
+    transact(change) {
+      if (closed) return Promise.reject(new OperationError("store_closed"));
+      return enqueue(async () => {
+        if (poisoned) throw new OperationError("commit_unknown");
+        const state = structuredClone(await readState(directory));
+        const result = structuredClone(await change(state));
+        try {
+          await writeState(directory, structuredClone(state), fault);
+        } catch (error) {
+          if (error instanceof OperationError && error.code === "commit_unknown") poisoned = true;
+          throw error;
+        }
+        return result;
+      });
+    },
+    close() {
+      if (closed) return tail;
+      closed = true;
+      return enqueue(async () => {
+        await unlockOwned(lock, identity);
+      });
+    }
+  };
+}
+
+// src/policy.ts
+import { validateComponentTree } from "@ai-slot/registry";
+var MAX_TREE_BYTES = 64 * 1024;
+function authorize(actor, slotId, action) {
+  if (!actor.grants || !Object.hasOwn(actor.grants, slotId) || !Array.isArray(actor.grants[slotId]) || !actor.grants[slotId].includes(action)) {
+    throw new OperationError("forbidden");
+  }
+}
+function normalizeNode(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return;
+  const node = value;
+  if (!Object.hasOwn(node, "props")) node.props = {};
+  if (Array.isArray(node.children)) for (const child of node.children) normalizeNode(child);
+  if (node.slots !== null && typeof node.slots === "object" && !Array.isArray(node.slots)) {
+    for (const children of Object.values(node.slots)) {
+      if (Array.isArray(children)) for (const child of children) normalizeNode(child);
+    }
+  }
+}
+function validateArtifact(env, slotId, tree, source) {
+  const policy = Object.hasOwn(env.policies, slotId) ? env.policies[slotId] : void 0;
+  if (!policy) throw new OperationError("forbidden");
+  const activePolicy = policy;
+  if (!source || typeof source !== "object" || Array.isArray(source) || typeof source.id !== "string" || !source.id.trim() || source.id !== policy.sourceId || typeof source.version !== "string" || !source.version.trim() || !Number.isFinite(source.expiresAt) || !source.data || typeof source.data !== "object" || Array.isArray(source.data)) {
+    throw new OperationError("source_invalid");
+  }
+  if (source.expiresAt <= env.now()) throw new OperationError("expired");
+  let snapshot;
+  try {
+    const encoded = canonical(tree);
+    if (Buffer.byteLength(encoded, "utf8") > MAX_TREE_BYTES) throw new OperationError("invalid_tree");
+    snapshot = JSON.parse(encoded);
+    normalizeNode(snapshot);
+  } catch {
+    throw new OperationError("invalid_tree");
+  }
+  if (!validateComponentTree(env.registry, snapshot).ok) throw new OperationError("invalid_tree");
+  const root = snapshot;
+  function visit(node) {
+    if (!activePolicy.allowedComponents.includes(node.component)) throw new OperationError("component_denied");
+    for (const rule of activePolicy.lockedProps) {
+      if (rule.component !== node.component) continue;
+      if (!Object.hasOwn(source.data, rule.sourceField) || !Object.hasOwn(node.props ?? {}, rule.prop)) {
+        throw new OperationError("locked_prop");
+      }
+      try {
+        if (canonical(node.props?.[rule.prop]) !== canonical(source.data[rule.sourceField])) {
+          throw new OperationError("locked_prop");
+        }
+      } catch {
+        throw new OperationError("locked_prop");
+      }
+    }
+    for (const rule of activePolicy.urlProps) {
+      if (rule.component !== node.component) continue;
+      let url;
+      try {
+        url = new URL(String(node.props?.[rule.prop]));
+      } catch {
+        throw new OperationError("url_denied");
+      }
+      if (url.protocol !== "https:" || url.username || url.password || !activePolicy.allowedOrigins.includes(url.origin)) {
+        throw new OperationError("url_denied");
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+    for (const children of Object.values(node.slots ?? {})) for (const child of children) visit(child);
+  }
+  visit(root);
+  return root;
+}
+
+// src/drafts.ts
+import { randomUUID as randomUUID2 } from "crypto";
+async function readSource(env, slotId) {
+  try {
+    return await env.readSource(slotId);
+  } catch {
+    throw new OperationError("source_unavailable");
+  }
+}
+async function assertCurrentArtifact(env, artifact) {
+  const policy = Object.hasOwn(env.policies, artifact.slotId) ? env.policies[artifact.slotId] : void 0;
+  if (!policy || artifact.registryVersion !== policy.registryVersion || artifact.rendererVersion !== policy.rendererVersion) {
+    throw new OperationError("contract_changed");
+  }
+  if (artifact.sourceId !== policy.sourceId) throw new OperationError("source_changed");
+  const source = await readSource(env, artifact.slotId);
+  validateArtifact(env, artifact.slotId, artifact.tree, source);
+  if (source.id !== artifact.sourceId || source.version !== artifact.sourceVersion || source.expiresAt !== artifact.expiresAt) {
+    throw new OperationError("source_changed");
+  }
+  if (artifact.expiresAt <= env.now()) throw new OperationError("expired");
+}
+function requireDraftInput(input) {
+  if (!input || typeof input.slotId !== "string" || !input.slotId || !Number.isSafeInteger(input.baseRevision) || input.baseRevision < 0 || typeof input.sourceVersion !== "string" || !input.sourceVersion) {
+    throw new OperationError("invalid_input");
+  }
+}
+function createDraft(store, env, actor, input) {
+  requireDraftInput(input);
+  return store.transact(async (state) => {
+    authorize(actor, input.slotId, "draft");
+    const policy = Object.hasOwn(env.policies, input.slotId) ? env.policies[input.slotId] : void 0;
+    if (!policy) throw new OperationError("forbidden");
+    if (input.baseRevision !== (state.pointers[input.slotId]?.revision ?? 0)) throw new OperationError("revision_conflict");
+    const source = await readSource(env, input.slotId);
+    const tree = validateArtifact(env, input.slotId, input.tree, source);
+    if (source.version !== input.sourceVersion) throw new OperationError("source_changed");
+    const payload = {
+      slotId: input.slotId,
+      tree,
+      sourceId: source.id,
+      sourceVersion: source.version,
+      registryVersion: policy.registryVersion,
+      rendererVersion: policy.rendererVersion,
+      expiresAt: source.expiresAt
+    };
+    const artifact = { hash: hash(payload), ...payload };
+    const existing = state.artifacts[artifact.hash];
+    if (existing && canonical(existing) !== canonical(artifact)) throw new OperationError("hash_collision");
+    if (!existing) state.artifacts[artifact.hash] = artifact;
+    const draft = {
+      id: randomUUID2(),
+      artifactHash: artifact.hash,
+      slotId: input.slotId,
+      baseRevision: input.baseRevision,
+      createdBy: actor.id,
+      intent: "publish",
+      createdAt: env.now()
+    };
+    state.drafts[draft.id] = draft;
+    return draft;
+  });
+}
+async function previewDraft(store, _env, actor, draftId) {
+  const state = await store.read();
+  const draft = Object.hasOwn(state.drafts, draftId) ? state.drafts[draftId] : void 0;
+  if (!draft) throw new OperationError("draft_not_found");
+  authorize(actor, draft.slotId, "read");
+  const artifact = state.artifacts[draft.artifactHash];
+  if (!artifact) throw new OperationError("corrupt_state");
+  const release = state.releases.find((r) => r.slotId === draft.slotId && r.revision === draft.baseRevision);
+  const previous = release ? state.artifacts[release.artifactHash] ?? null : null;
+  return structuredClone({ draft, artifact, previous });
+}
+function approveDraft(store, env, actor, input) {
+  if (!input || typeof input.draftId !== "string" || typeof input.artifactHash !== "string" || typeof input.expiresAt !== "number" || !Number.isFinite(input.expiresAt)) throw new OperationError("invalid_input");
+  return store.transact(async (state) => {
+    const draft = Object.hasOwn(state.drafts, input.draftId) ? state.drafts[input.draftId] : void 0;
+    if (!draft) throw new OperationError("draft_not_found");
+    authorize(actor, draft.slotId, "approve");
+    if (draft.artifactHash !== input.artifactHash) throw new OperationError("hash_mismatch");
+    if (draft.baseRevision !== (state.pointers[draft.slotId]?.revision ?? 0)) throw new OperationError("revision_conflict");
+    const artifact = state.artifacts[draft.artifactHash];
+    if (!artifact) throw new OperationError("corrupt_state");
+    await assertCurrentArtifact(env, artifact);
+    const now = env.now();
+    if (!(input.expiresAt > now && input.expiresAt <= Math.min(now + 15 * 6e4, artifact.expiresAt))) {
+      throw new OperationError("invalid_expiry");
+    }
+    const approval = {
+      draftId: draft.id,
+      artifactHash: artifact.hash,
+      baseRevision: draft.baseRevision,
+      approvedBy: actor.id,
+      expiresAt: input.expiresAt
+    };
+    state.approvals[draft.id] = approval;
+    return approval;
+  });
+}
+function prepareRollback(store, env, actor, input) {
+  if (!input || typeof input.slotId !== "string" || !input.slotId || !Number.isSafeInteger(input.targetRevision) || input.targetRevision < 1 || !Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
+    throw new OperationError("invalid_input");
+  }
+  return store.transact(async (state) => {
+    authorize(actor, input.slotId, "rollback");
+    if (input.expectedRevision !== (state.pointers[input.slotId]?.revision ?? 0)) throw new OperationError("conflict");
+    const release = state.releases.find((r) => r.slotId === input.slotId && r.revision === input.targetRevision);
+    if (!release) throw new OperationError("not_found");
+    const artifact = state.artifacts[release.artifactHash];
+    if (!artifact) throw new OperationError("corrupt_state");
+    await assertCurrentArtifact(env, artifact);
+    const draft = {
+      id: randomUUID2(),
+      artifactHash: artifact.hash,
+      slotId: input.slotId,
+      baseRevision: input.expectedRevision,
+      createdBy: actor.id,
+      intent: "rollback",
+      createdAt: env.now()
+    };
+    state.drafts[draft.id] = draft;
+    return draft;
+  });
+}
+
+// src/publishing.ts
+async function assertPublishable(state, env, draft, input) {
+  const artifact = state.artifacts[draft.artifactHash];
+  const approval = state.approvals[draft.id];
+  if (!artifact || !approval) throw new OperationError("approval_required");
+  if (input.artifactHash !== artifact.hash || approval.artifactHash !== artifact.hash) throw new OperationError("hash_mismatch");
+  const current = state.pointers[draft.slotId]?.revision ?? 0;
+  if (current !== input.expectedRevision || current !== draft.baseRevision || current !== approval.baseRevision) {
+    throw new OperationError("conflict");
+  }
+  if (approval.expiresAt <= env.now()) throw new OperationError("approval_expired");
+  await assertCurrentArtifact(env, artifact);
+  if (approval.expiresAt <= env.now()) throw new OperationError("approval_expired");
+}
+async function commitDraft(store, env, actor, input, action) {
+  if (!input || typeof input.draftId !== "string" || !input.draftId || typeof input.artifactHash !== "string" || !input.artifactHash || !Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
+    throw new OperationError("invalid_input");
+  }
+  const receipt = await store.transact(async (state) => {
+    const draft = Object.hasOwn(state.drafts, input.draftId) ? state.drafts[input.draftId] : void 0;
+    if (!draft) throw new OperationError("not_found");
+    authorize(actor, draft.slotId, action);
+    if (draft.intent !== action) throw new OperationError("wrong_action");
+    if (typeof input.idempotencyKey !== "string" || !/^[a-zA-Z0-9_-]{1,100}$/.test(input.idempotencyKey)) {
+      throw new OperationError("invalid_key");
+    }
+    const key = hash([actor.id, draft.slotId, action, input.idempotencyKey]);
+    const fingerprint = hash(input);
+    const previous = Object.hasOwn(state.idempotency, key) ? state.idempotency[key] : void 0;
+    if (previous) {
+      if (previous.fingerprint !== fingerprint) throw new OperationError("idempotency_conflict");
+      return previous.receipt;
+    }
+    await assertPublishable(state, env, draft, input);
+    const revision2 = (state.pointers[draft.slotId]?.revision ?? 0) + 1;
+    const result = { slotId: draft.slotId, revision: revision2, artifactHash: draft.artifactHash };
+    state.releases.push({ ...result, draftId: draft.id, actor: actor.id, action, at: env.now() });
+    state.pointers[draft.slotId] = result;
+    state.idempotency[key] = { fingerprint, receipt: result };
+    return result;
+  });
+  try {
+    await env.notify(receipt.slotId);
+  } catch {
+  }
+  return receipt;
+}
+
+// src/delivery.ts
+var headers = { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" };
+async function readableArtifact(state, env, slotId, pointer) {
+  if (!pointer || pointer.slotId !== slotId) return null;
+  const artifact = Object.hasOwn(state.artifacts, pointer.artifactHash) ? state.artifacts[pointer.artifactHash] : void 0;
+  if (!artifact || artifact.hash !== pointer.artifactHash || artifact.slotId !== slotId) return null;
+  try {
+    await assertCurrentArtifact(env, artifact);
+  } catch {
+    return null;
+  }
+  return artifact;
+}
+async function deliver(store, env, slotId) {
+  if (!Object.hasOwn(env.policies, slotId)) {
+    return new Response(JSON.stringify({ error: "not_found" }), { status: 404, headers });
+  }
+  try {
+    const state = await store.read();
+    const pointer = Object.hasOwn(state.pointers, slotId) ? state.pointers[slotId] : void 0;
+    const artifact = await readableArtifact(state, env, slotId, pointer);
+    if (pointer && artifact) {
+      return new Response(JSON.stringify({
+        version: 1,
+        slot: slotId,
+        tree: artifact.tree,
+        meta: {
+          revision: pointer.revision,
+          artifactHash: artifact.hash,
+          sourceVersion: artifact.sourceVersion,
+          expiresAt: artifact.expiresAt
+        }
+      }), { headers });
+    }
+  } catch {
+  }
+  return new Response(JSON.stringify({ error: "ai_unavailable" }), { status: 503, headers });
+}
+async function getStatus(store, env, actor, slotId) {
+  authorize(actor, slotId, "read");
+  if (!Object.hasOwn(env.policies, slotId)) throw new OperationError("not_found");
+  const state = await store.read();
+  const pointer = Object.hasOwn(state.pointers, slotId) ? state.pointers[slotId] : void 0;
+  const artifact = await readableArtifact(state, env, slotId, pointer);
+  return {
+    desiredRevision: pointer?.revision ?? 0,
+    readableRevision: pointer && artifact ? pointer.revision : null,
+    browserObservation: null
+  };
+}
+
+// src/operations.ts
+function createOperations(store, env) {
+  return {
+    async listSlots(actor) {
+      return Object.keys(env.policies).filter((slotId) => {
+        try {
+          authorize(actor, slotId, "read");
+          return true;
+        } catch {
+          return false;
+        }
+      }).sort();
+    },
+    async readSlot(actor, slotId) {
+      authorize(actor, slotId, "read");
+      if (!Object.hasOwn(env.policies, slotId)) throw new OperationError("not_found");
+      const state = await store.read();
+      return structuredClone({
+        pointer: state.pointers[slotId] ?? null,
+        drafts: Object.values(state.drafts).filter((draft) => draft.slotId === slotId)
+      });
+    },
+    createDraft: (actor, input) => createDraft(store, env, actor, input),
+    previewDraft: (actor, draftId) => previewDraft(store, env, actor, draftId),
+    approveDraft: (actor, input) => approveDraft(store, env, actor, input),
+    publishDraft: (actor, input) => commitDraft(store, env, actor, input, "publish"),
+    prepareRollback: (actor, input) => prepareRollback(store, env, actor, input),
+    rollbackSlot: (actor, input) => commitDraft(store, env, actor, input, "rollback"),
+    getStatus: (actor, slotId) => getStatus(store, env, actor, slotId),
+    deliver: (slotId) => deliver(store, env, slotId)
+  };
+}
+export {
+  OperationError,
+  approveDraft,
+  assertCurrentArtifact,
+  assertState,
+  authorize,
+  canonical,
+  commitDraft,
+  createDraft,
+  createOperations,
+  deliver,
+  emptyState,
+  getStatus,
+  hash,
+  openFileStore,
+  prepareRollback,
+  previewDraft,
+  readSource,
+  validateArtifact
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@ai-slot/operations",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ai-slot/registry": "0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iannil/ai-slot-component.git",
+    "directory": "packages/operations"
+  },
+  "bugs": {
+    "url": "https://github.com/iannil/ai-slot-component/issues"
+  },
+  "homepage": "https://github.com/iannil/ai-slot-component/tree/master/packages/operations#readme",
+  "description": "Experimental single-writer local version store and approval/publish governance for AI-SLOT.",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }