@hypit/hypit 0.1.3 → 0.1.5

package/packages/build-result/src/file-reference.ts

@@ -0,0 +1,42 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import type { BuildResultFileRange, BuildResultFileRef } from "./types.js";
+
+/** Address access belongs to the Repository adapter, not the value or domain graph. */
+export type ExternalFileAccess = {
+  size(uri: string): Promise<number>;
+  open(uri: string, range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array>>;
+};
+
+/** The Node distribution's external files are explicit file: URLs supplied by its Workspace. */
+export const localExternalFiles: ExternalFileAccess = {
+  async size(uri) { return (await stat(fileURLToPath(uri))).size; },
+  async open(uri, range) {
+    if (range !== undefined) {
+      const size = await localExternalFiles.size(uri);
+      if (!Number.isSafeInteger(range.start) || range.start < 0
+        || !Number.isSafeInteger(range.endExclusive) || range.endExclusive <= range.start
+        || range.endExclusive > size) throw new Error(`Invalid file range for ${uri}`);
+    }
+    return createReadStream(fileURLToPath(uri), range === undefined ? {} : { start: range.start, end: range.endExclusive - 1 });
+  },
+};
+
+export function fileReferenceIdentity(owner: string, file: BuildResultFileRef): string {
+  return file.kind === "external-file" ? JSON.stringify(["external", file.uri])
+    : JSON.stringify(["result", file.build ?? owner, file.path]);
+}
+
+/** Make a relative Result file reference independent of its enclosing value document. */
+export function ownedFileReference(owner: string, file: BuildResultFileRef): BuildResultFileRef {
+  return file.kind === "build-file" ? { ...file, build: file.build ?? owner } : file;
+}
+
+/** Reopening an external reference reads its current metadata, without comparing versions. */
+export async function currentFileReference(
+  file: BuildResultFileRef,
+  access: ExternalFileAccess = localExternalFiles,
+): Promise<BuildResultFileRef> {
+  return file.kind === "external-file" ? { ...file, size: await access.size(file.uri) } : file;
+}

package/packages/build-result/src/index.ts

@@ -23,3 +23,7 @@ export {
 } from "./store.js";
 export type * from "./types.js";
 export type * from "./writer.js";
+
+export { currentFileReference, fileReferenceIdentity, ownedFileReference, localExternalFiles } from "./file-reference.js";
+export type { ExternalFileAccess } from "./file-reference.js";
+export { preserveExecutionLog } from "./execution-log.js";

package/packages/build-result/src/replace-file-windows.ts

@@ -0,0 +1,58 @@
+import { toNamespacedPath } from "node:path";
+import koffi from "koffi";
+
+const kernel = koffi.load("kernel32.dll");
+const createFile = kernel.func("intptr_t __stdcall CreateFileW(const char16_t *path, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t attributes, intptr_t templateFile)");
+const setInformation = kernel.func("int __stdcall SetFileInformationByHandle(intptr_t file, int infoClass, void *info, uint32_t size)");
+const closeHandle = kernel.func("int __stdcall CloseHandle(intptr_t file)");
+const getLastError = kernel.func("uint32_t __stdcall GetLastError()");
+
+const renameInfo = koffi.struct({
+  Flags: "uint32_t",
+  RootDirectory: "void *",
+  FileNameLength: "uint32_t",
+  FileName: koffi.array("uint16_t", 1),
+});
+
+const DELETE = 0x00010000;
+const SHARE_READ_WRITE_DELETE = 0x7;
+const OPEN_EXISTING = 3;
+const FILE_ATTRIBUTE_NORMAL = 0x80;
+const FileRenameInfoEx = 22;
+const REPLACE_IF_EXISTS = 0x1;
+const POSIX_SEMANTICS = 0x2;
+
+function failure(syscall: string, from: string, to: string): Error {
+  const win32Code = getLastError() as number;
+  return Object.assign(new Error(`Windows file replacement failed (${win32Code}): '${from}' -> '${to}'`), {
+    code: `WIN32_${win32Code}`, win32Code, syscall, path: from, dest: to,
+  });
+}
+
+/**
+ * FileRenameInfoEx preserves open readers of the old file while publishing the new name.
+ * Node's Windows rename uses MoveFileExW, whose replacement semantics differ here.
+ * https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/4217551b-d2c0-42cb-9dc1-69a716cf6d0c
+ */
+export function replaceWindowsFile(from: string, to: string): void {
+  const filename = Buffer.from(toNamespacedPath(to), "utf16le");
+  const nameOffset = koffi.offsetof(renameInfo, "FileName");
+  // Win32 requires a NUL-terminated FileName even though FileNameLength excludes
+  // that terminator. Buffer.alloc leaves the final WCHAR zero-initialized.
+  // https://learn.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_rename_info
+  const info = Buffer.alloc(Math.max(koffi.sizeof(renameInfo), nameOffset + filename.length + 2));
+  info.writeUInt32LE(REPLACE_IF_EXISTS | POSIX_SEMANTICS, koffi.offsetof(renameInfo, "Flags"));
+  info.writeUInt32LE(filename.length, koffi.offsetof(renameInfo, "FileNameLength"));
+  filename.copy(info, nameOffset);
+
+  const handle = createFile(toNamespacedPath(from), DELETE, SHARE_READ_WRITE_DELETE,
+    null, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, 0) as number | bigint;
+  if (handle === -1 || handle === -1n) throw failure("CreateFileW", from, to);
+  try {
+    if (!setInformation(handle, FileRenameInfoEx, info, info.length)) {
+      throw failure("SetFileInformationByHandle", from, to);
+    }
+  } finally {
+    closeHandle(handle);
+  }
+}

package/packages/build-result/src/replace-file.ts

@@ -0,0 +1,11 @@
+import { rename } from "node:fs/promises";
+
+/** Publish a complete file without changing the bytes held by existing readers. */
+export async function replaceFile(from: string, to: string): Promise<void> {
+  if (process.platform === "win32") {
+    const { replaceWindowsFile } = await import("./replace-file-windows.js");
+    replaceWindowsFile(from, to);
+  } else {
+    await rename(from, to);
+  }
+}

package/packages/build-result/src/store.ts

@@ -1,3 +1,6 @@
+import { preserveExecutionLog } from "./execution-log.js";
+import { currentFileReference, localExternalFiles } from "./file-reference.js";
+import type { ExternalFileAccess } from "./file-reference.js";
 import { randomUUID } from "node:crypto";
 import {
   mkdir,
@@ -40,6 +43,7 @@ import {
   encodeBuildResultManifest,
 } from "./decode.js";
 import { syncBuildResultOutputs } from "./writer.js";
+import { replaceFile } from "./replace-file.js";
 
 const manifestName = "result.json";
 const writerStateName = ".writer.json";
@@ -83,6 +87,22 @@ export function applyBuildResultPresentation(
     if (highlighted.length === 0) delete base.highlightedOutputs;
     else base.highlightedOutputs = highlighted;
   }
+  if (update.outputDisplayNames !== undefined) {
+    const outputs = { ...manifest.outputs };
+    for (const [name, value] of Object.entries(update.outputDisplayNames)) {
+      const entry = manifest.outputs[name];
+      assert(Object.hasOwn(manifest.outputs, name) && entry !== undefined,
+        `Build Result ${manifest.id} has no Output ${name}`);
+      const { displayName: _priorName, ...rest } = entry;
+      if (value === null) outputs[name] = rest;
+      else {
+        const displayName = value.trim();
+        assert(displayName.length > 0, "Output display name must not be empty");
+        outputs[name] = { ...rest, displayName };
+      }
+    }
+    return { ...base, outputs };
+  }
   return base;
 }
 
@@ -95,7 +115,7 @@ async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
   const temporary = `${path}.part-${randomUUID()}`;
   try {
     await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
-    await rename(temporary, path);
+    await replaceFile(temporary, path);
   } catch (error) {
     await rm(temporary, { force: true });
     throw error;
@@ -115,15 +135,24 @@ async function copyArtifactAtomic(
   await mkdir(dirname(destination), { recursive: true });
   const input = await source.open(artifact);
   if (input === undefined) throw new Error(`Build resource ${artifact.resource} is unavailable`);
+  await writeStreamAtomic(destination, input);
+}
+
+async function writeStreamAtomic(destination: string, input: AsyncIterable<Uint8Array>): Promise<void> {
+  await mkdir(dirname(destination), { recursive: true });
   const temporary = `${destination}.part-${randomUUID()}`;
   const output = await open(temporary, "wx");
   try {
     for await (const value of input) {
       const chunk = Uint8Array.from(value);
-      await output.write(chunk);
+      let offset = 0;
+      while (offset < chunk.byteLength) {
+        const { bytesWritten } = await output.write(chunk, offset, chunk.byteLength - offset);
+        offset += bytesWritten;
+      }
     }
     await output.close();
-    await rename(temporary, destination);
+    await replaceFile(temporary, destination);
   } catch (error) {
     await output.close().catch(() => undefined);
     await rm(temporary, { force: true });
@@ -221,6 +250,7 @@ export async function resolveBuildResultOutput(
   root: string,
   build: string,
   output: string,
+  externalFiles: ExternalFileAccess = localExternalFiles,
 ): Promise<ResolvedBuildResultOutput | undefined> {
   const seen = new Set<string>();
   let currentBuild = build;
@@ -254,14 +284,14 @@ export async function resolveBuildResultOutput(
       };
     }
     const terminalKind = (entry.value as { readonly kind?: unknown }).kind;
-    assert(terminalKind === "build-file" || terminalKind === "inline",
+    assert(terminalKind === "build-file" || terminalKind === "external-file" || terminalKind === "inline",
       `Build ${currentBuild} Output ${currentOutput} has unsupported Result value kind ${String(terminalKind)}`);
     return {
       build: currentBuild,
       output: currentOutput,
       directory,
       type: entry.type,
-      value: entry.value,
+      value: entry.value.kind === "external-file" ? await currentFileReference(entry.value, externalFiles) : entry.value,
     };
   }
 }
@@ -270,6 +300,7 @@ export async function describeBuildResultOutput(
   root: string,
   build: string,
   output: string,
+  externalFiles: ExternalFileAccess = localExternalFiles,
 ): Promise<RepositoryBuildResultOutputDescription | undefined> {
   const seen = new Set<string>();
   let currentBuild = build;
@@ -286,8 +317,9 @@ export async function describeBuildResultOutput(
       currentOutput = entry.value.output;
       continue;
     }
-    return entry.value.kind === "build-file"
-      ? { type: entry.type, kind: "resource", size: entry.value.size, mediaType: entry.value.mediaType }
+    const file = entry.value.kind === "external-file" ? await currentFileReference(entry.value, externalFiles) : entry.value;
+    return file.kind === "build-file" || file.kind === "external-file"
+      ? { type: entry.type, kind: "resource", size: file.size, mediaType: file.mediaType }
       : entry.value.kind === "value"
         ? { type: entry.type, kind: "composite" }
         : { type: entry.type, kind: "scalar" };
@@ -334,12 +366,12 @@ export class FileBuildResult {
     this.directory = resolve(directory);
   }
 
-  static async create(root: string, seed: BuildResultSeed): Promise<FileBuildResult> {
+  static async create(root: string, seed: BuildResultSeed, externalFiles: ExternalFileAccess = localExternalFiles): Promise<FileBuildResult> {
     assertOrderedBuildId(seed.id);
     assertBuildResultSeed(seed);
     const forwards = await normalizeBuildResultForwards({
       read: async (build) => await readBuildResult(buildResultDirectory(root, build)),
-      resolve: async (build, output) => await resolveBuildResultOutput(root, build, output),
+      resolve: async (build, output) => await resolveBuildResultOutput(root, build, output, externalFiles),
     }, seed.forwards ?? []);
     const directory = buildResultDirectory(root, seed.id);
     await mkdir(dirname(directory), { recursive: true });
@@ -360,6 +392,7 @@ export class FileBuildResult {
         resources: {},
         values: {},
         publishedOutputs: seed.publishedOutputs,
+        ...(seed.resourceReferences === undefined ? {} : { resourceReferences: seed.resourceReferences }),
         forwards,
       });
       await rename(temporary, directory);
@@ -405,6 +438,7 @@ export class FileBuildResult {
         },
       },
     });
+    if (!updated.changed) return manifest;
     await writeJsonAtomic(join(this.directory, writerStateName), updated.writer);
     await writeManifestAtomic(join(this.directory, manifestName), updated.manifest);
     return updated.manifest;
@@ -418,10 +452,13 @@ export class FileBuildResult {
       await rm(join(this.directory, writerStateName), { force: true });
       return manifest;
     }
+    const executionLog = await preserveExecutionLog(input.executionLog,
+      async (path, chunks) => await writeStreamAtomic(join(this.directory, path), chunks));
     const now = Date.now();
     const updated: BuildResultManifest = {
       ...manifest,
       outcome: input.outcome,
+      ...(executionLog === undefined ? {} : { executionLog }),
       ...(input.operations === undefined ? {} : { operations: input.operations }),
       finishedAt: manifest.finishedAt ?? now,
       ...(input.failure === undefined ? {} : { failure: input.failure }),
@@ -434,15 +471,17 @@ export class FileBuildResult {
 
 /** Default zero-configuration project repository backed by one ordinary directory tree. */
 export class FileBuildResultRepository implements BuildResultRepository {
+  readonly externalFiles: ExternalFileAccess;
   readonly root: string;
 
-  constructor(root: string) {
+  constructor(root: string, externalFiles: ExternalFileAccess = localExternalFiles) {
+    this.externalFiles = externalFiles;
     assert(root.trim().length > 0, "Build Result root must not be empty");
     this.root = resolve(root);
   }
 
   async create(seed: BuildResultSeed): Promise<FileBuildResult> {
-    return await FileBuildResult.create(this.root, seed);
+    return await FileBuildResult.create(this.root, seed, this.externalFiles);
   }
 
   async openWriter(build: string): Promise<FileBuildResult | undefined> {
@@ -477,22 +516,27 @@ export class FileBuildResultRepository implements BuildResultRepository {
   }
 
   async describeOutput(build: string, output: string): Promise<RepositoryBuildResultOutputDescription | undefined> {
-    return await describeBuildResultOutput(this.root, build, output);
+    return await describeBuildResultOutput(this.root, build, output, this.externalFiles);
   }
 
   async resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined> {
-    const resolvedOutput = await resolveBuildResultOutput(this.root, build, output);
+    const resolvedOutput = await resolveBuildResultOutput(this.root, build, output, this.externalFiles);
     if (resolvedOutput === undefined) return undefined;
     const { directory: _directory, ...portable } = resolvedOutput;
     return portable;
   }
 
+  async describeFile(_build: string, file: BuildResultFileRef): Promise<BuildResultFileRef> {
+    return await currentFileReference(file, this.externalFiles);
+  }
+
   async openFile(
     build: string,
     file: BuildResultFileRef,
     range?: BuildResultFileRange,
   ): Promise<AsyncIterable<Uint8Array> | undefined> {
-    const directory = buildResultDirectory(this.root, build);
+    if (file.kind === "external-file") return await this.externalFiles.open(file.uri, range);
+    const directory = buildResultDirectory(this.root, file.build ?? build);
     const path = containedResultPath(directory, file.path);
     if (!await exists(path)) return undefined;
     if (range === undefined) return createReadStream(path);

package/packages/build-result/src/types.ts

@@ -1,3 +1,4 @@
+import { assertOrderedBuildId } from "@hypit/protocol";
 import type {
   BlobRef,
   BuildState,
@@ -9,12 +10,19 @@ import type {
 export type BuildResultOutcome = "complete" | "failed" | "cancelled";
 
 export type BuildResultFileRef = {
+  readonly size: number;
+  readonly mediaType: string;
+} & ({
   readonly kind: "build-file";
+  /** Absent for a file owned by the containing Result; explicit when reused elsewhere. */
+  readonly build?: string;
   /** Forward-only path relative to the owning Build's result directory. */
   readonly path: string;
-  readonly size: number;
-  readonly mediaType: string;
-};
+} | {
+  readonly kind: "external-file";
+  /** Explicit address supplied by the Workspace; remains a live external dependency. */
+  readonly uri: string;
+});
 
 /** A normalized half-open byte range within one Result file. */
 export type BuildResultFileRange = {
@@ -38,7 +46,7 @@ export type BuildResultResourceBinding = {
 
 /**
  * Durable encoding of one Composite value. Domain data stays ordinary canonical data while
- * Result-local Resource addresses live beside it, so reserved-looking domain objects cannot be
+ * Resource references live beside it, so reserved-looking domain objects cannot be
  * mistaken for persistence metadata.
  */
 export type BuildResultValueDocument = {
@@ -77,12 +85,18 @@ export function assertBuildResultFileRef(value: unknown, subject: string): asser
     throw new Error(`${subject} is not a Build file reference`);
   }
   const item = value as Readonly<Record<string, unknown>>;
-  if (item.kind !== "build-file"
+  if ((item.kind !== "build-file" && item.kind !== "external-file")
     || typeof item.size !== "number" || !Number.isSafeInteger(item.size) || item.size < 0
     || typeof item.mediaType !== "string" || item.mediaType.length === 0) {
     throw new Error(`${subject} is not a valid Build file reference`);
   }
-  assertBuildResultPath(item.path, `${subject}.path`);
+  if (item.kind === "external-file") {
+    if (typeof item.uri !== "string" || item.uri.length === 0) throw new Error(`${subject}.uri is missing`);
+    new URL(item.uri);
+  } else {
+    assertBuildResultPath(item.path, `${subject}.path`);
+    if (item.build !== undefined) assertOrderedBuildId(item.build as string);
+  }
 }
 
 function valueAtPath(value: CanonicalValue, path: BuildResultValuePath, subject: string): CanonicalValue {
@@ -150,6 +164,8 @@ export type BuildResultOutputValue =
   | { readonly kind: "value"; readonly path: string };
 
 export type BuildResultOutput = {
+  /** Author-provided display name; the Output identifier remains unchanged. */
+  readonly displayName?: string;
   readonly type: TypeRef;
   readonly value: BuildResultOutputValue;
 };
@@ -190,6 +206,7 @@ export type BuildResultManifest = {
   readonly failure?: string;
   readonly outputs: Readonly<Record<string, BuildResultOutput>>;
   readonly operations?: readonly BuildResultOperation[];
+  readonly executionLog?: BuildResultFileRef;
 };
 
 export type FinishedBuildResultManifest = BuildResultManifest & {
@@ -198,6 +215,8 @@ export type FinishedBuildResultManifest = BuildResultManifest & {
 };
 
 export type BuildResultPublishedOutput = {
+  /** Author-provided display name; the Output identifier remains unchanged. */
+  readonly displayName?: string;
   readonly name: string;
   readonly output: string;
 };
@@ -217,6 +236,8 @@ export type BuildResultSeed = {
   readonly targets: readonly string[];
   readonly publishedOutputs: readonly BuildResultPublishedOutput[];
   readonly forwards?: readonly BuildResultForward[];
+  /** Known file locations for admitted Resource identities, including nested uses. */
+  readonly resourceReferences?: Readonly<Record<string, BuildResultFileRef>>;
 };
 
 /** Validate the one-name-per-Output public Result surface before storage is touched. */
@@ -224,6 +245,11 @@ export function assertBuildResultSeed(seed: BuildResultSeed): void {
   if (seed.title !== undefined && seed.title.trim().length === 0) {
     throw new Error("Build Result title must not be empty");
   }
+  for (const [resource, file] of Object.entries(seed.resourceReferences ?? {})) {
+    if (resource.length === 0) throw new Error("Resource reference has no identity");
+    assertBuildResultFileRef(file, `Resource ${resource}`);
+    if (file.kind === "build-file" && file.build === undefined) throw new Error(`Resource ${resource} needs its owning Build`);
+  }
   const names = new Set<string>();
   const outputs = new Set<string>();
   for (const published of seed.publishedOutputs) {
@@ -269,12 +295,16 @@ export type BuildResultSync = {
 };
 
 export type BuildResultFinish = {
+  /** Closed execution evidence; Repository stores it before publishing the terminal manifest. */
+  readonly executionLog?: AsyncIterable<Uint8Array>;
   readonly operations?: readonly BuildResultOperation[];
   readonly outcome: BuildResultOutcome;
   readonly failure?: string;
 };
 
 export type BuildResultPresentationUpdate = {
+  /** Exact public Output names; null removes an override. */
+  readonly outputDisplayNames?: Readonly<Record<string, string | null>>;
   /** `null` removes the current title; omission leaves it unchanged. */
   readonly title?: string | null;
   /** `null` removes the current note; omission leaves it unchanged. */
@@ -325,13 +355,14 @@ export type RepositoryBuildResultOutputDescription = {
 
 export type BuildResultWriter = {
   read(): Promise<BuildResultManifest>;
+  /** Publish newly accepted public Outputs; no storage writes when none are new. */
   sync(input: BuildResultSync): Promise<BuildResultManifest>;
   finish(input: BuildResultFinish): Promise<BuildResultManifest>;
 };
 
 /**
- * Project result history addressed only by Build id, Output name and Build-relative file path.
- * Filesystem paths, bucket keys and service URLs remain implementation details.
+ * Project result history addressed by Build id and Output name. File references carry their
+ * ownership or explicit external address; each repository supplies the corresponding byte access.
  */
 export type BuildResultRepository = {
   create(seed: BuildResultSeed): Promise<BuildResultWriter>;
@@ -346,6 +377,8 @@ export type BuildResultRepository = {
   /** Follow explicit Output forwarding and describe its terminal value without opening content. */
   describeOutput(build: string, output: string): Promise<RepositoryBuildResultOutputDescription | undefined>;
   resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined>;
+  /** Read current metadata for a file reference, including external dependencies. */
+  describeFile(build: string, file: BuildResultFileRef): Promise<BuildResultFileRef>;
   openFile(
     build: string,
     file: BuildResultFileRef,

package/packages/build-result/src/writer.ts

@@ -13,8 +13,9 @@ import type {
 
 export type BuildResultWriterState = {
   readonly resources: Readonly<Record<string, string>>;
+  readonly resourceReferences?: Readonly<Record<string, BuildResultFileRef>>;
   readonly values: Readonly<Record<string, string>>;
-  readonly publishedOutputs: readonly { readonly name: string; readonly output: string }[];
+  readonly publishedOutputs: readonly { readonly name: string; readonly output: string; readonly displayName?: string }[];
   readonly forwards: readonly { readonly output: string; readonly build: string; readonly sourceOutput: string }[];
 };
 
@@ -28,6 +29,8 @@ export type BuildResultWriteTarget = {
 };
 
 export type BuildResultSyncResult = {
+  /** Whether accepted public Outputs were added to the manifest. */
+  readonly changed: boolean;
   readonly manifest: BuildResultManifest;
   readonly writer: BuildResultWriterState;
 };
@@ -97,6 +100,8 @@ export async function syncBuildResultOutputs(input: {
   const outputs: Record<string, BuildResultOutput> = { ...input.manifest.outputs };
 
   const materialize = async (artifact: BlobRef): Promise<BuildResultFileRef> => {
+    const reference = input.writer.resourceReferences?.[artifact.resource];
+    if (reference !== undefined) return { ...reference, mediaType: artifact.mediaType };
     const identity = artifact.resource;
     assert(identity.length > 0, "Build resource has no instance identity");
     let path = resources.get(identity);
@@ -166,14 +171,20 @@ export async function syncBuildResultOutputs(input: {
   }).sort((left, right) => outputRank(left.record, left.forward) - outputRank(right.record, right.forward)
     || left.published.name.localeCompare(right.published.name));
 
+  if (ready.length === 0) {
+    return { changed: false, manifest: input.manifest, writer: input.writer };
+  }
+
   for (const { published, record, forward } of ready) {
     outputs[published.name] = {
+      ...(published.displayName === undefined ? {} : { displayName: published.displayName }),
       type: record.type,
       value: forward ?? await outputValue(record),
     };
   }
 
   return {
+    changed: true,
     manifest: { ...input.manifest, outputs },
     writer: {
       ...input.writer,

package/packages/build-result-fs/README.md

@@ -15,7 +15,7 @@ An explicit selection can move the same repository elsewhere:
 ```
 
 Relative paths are resolved from the project root. Results are grouped by the UTC date already encoded
-in their ordered Build ids, and each Build then owns one intact directory with its `result.json`, public
+in their ordered Build ids. Each Build has a directory containing its `result.json`, new public
 Resource files and Composite Value Documents:
 
 ```text
@@ -27,3 +27,25 @@ project-wide history database. Browsing sorts the shallow date buckets and enume
 only inside the dates reached while filling the requested cursor page; only those Result manifests are
 opened. File reads support byte ranges. Active diagnosis checks the selected directory (or its nearest
 existing parent) for read/write access without creating a probe file.
+
+Existing resources keep their addresses, including inside nested Composite values. External Workspace
+files remain live references; reused Result files retain their original owning Build. See the shared
+[Result value and reference model](../build-result/README.md) for ownership and export behavior.
+
+## Publication
+
+Runtime execution state stays in the Runtime's store. Result synchronization publishes newly accepted
+public Outputs: it saves new Resource files and Value Documents, then replaces `result.json`.
+Internal graph progress and already published Outputs cause no Result writes. A private `.writer.json`
+holds the file assignments needed while publishing and is removed at completion. The Runtime saves
+all accepted public Outputs and the final outcome before removing active execution state, including
+when the Build fails or is cancelled.
+
+Files are written completely beside their destination before publication. POSIX systems use `rename`;
+Windows uses `SetFileInformationByHandle(FileRenameInfoEx)` with replacement and POSIX semantics through
+Koffi. Existing readers keep their old file, while subsequent opens see the new one. This platform code
+belongs to the filesystem implementation; the Result model and other repository adapters do not
+depend on it. A filesystem that rejects this operation reports the Windows error without timed retries.
+
+The Windows behavior is defined by Microsoft's
+[FileRenameInformationEx documentation](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/4217551b-d2c0-42cb-9dc1-69a716cf6d0c).

package/packages/build-result-s3/README.md

@@ -33,6 +33,11 @@ The repository exposes the same logical shape as the filesystem adapter:
 Filesystem and S3 use the same Record-to-Result encoder. The adapter only writes the selected
 relative document or byte path; it does not interpret domain values. A Value Document keeps canonical
 domain data separate from the paths of nested Resources.
+Nested reuse retains each Resource's original Build and path. Workspace files remain explicit external
+references rather than being uploaded merely because this repository uses S3. The shared
+[Result value and reference model](../build-result/README.md) describes ownership and external access.
+Synchronization uploads new public Outputs and then their updated manifest. Internal graph progress
+and repeated synchronization of already published Outputs produce no object writes.
 
 Physical object prefixes use a reversible descending-time form derived from the ordered Build id, so
 S3 can return a newest-first delimiter page directly. This is only adapter key layout: callers still