@haverstack/core 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the Haverstack contributors have waived all
+copyright and related or neighboring rights to Haverstack. This work is
+published from the United States.
+
+https://creativecommons.org/publicdomain/zero/1.0/

package/README.md

@@ -0,0 +1,124 @@
+# @haverstack/core
+
+Core library for Haverstack — a portable personal data stack.
+
+Apps write **Records** into a **Stack**, and the stack handles storage, querying, versioning, and associations, regardless of where data actually lives. Switch backends without changing your app.
+
+> **Status:** Early development. APIs are unstable.
+
+## Installation
+
+```sh
+npm install @haverstack/core
+```
+
+You'll also need a storage adapter:
+
+- [`@haverstack/adapter-sqlite`](https://www.npmjs.com/package/@haverstack/adapter-sqlite) — local SQLite storage via sql.js
+
+## Quick start
+
+```ts
+import { Stack } from '@haverstack/core';
+import { SQLiteAdapter } from '@haverstack/adapter-sqlite';
+
+// First run — initialize a new stack
+const adapter = await SQLiteAdapter.initialize({
+  path: './my-stack.db',
+  entityId: 'my-entity-id',
+  timezone: 'America/New_York',
+});
+
+// Subsequent runs — open the existing stack
+// const adapter = await SQLiteAdapter.open({ path: './my-stack.db' });
+
+const stack = await Stack.create(adapter);
+
+// Define a type
+await stack.defineType('com.example.myapp/note@1', 'Note', {
+  text: { kind: 'text', required: true },
+  title: { kind: 'string' },
+});
+
+// Create a record
+const note = await stack.create('com.example.myapp/note@1', {
+  text: 'Hello, Haverstack!',
+  title: 'My first note',
+});
+
+// Update it (partial merge — only changed fields needed)
+await stack.update(note.id, { title: 'Updated title' });
+
+// Tag it
+await stack.associate(note.id, { kind: 'tag', label: 'favourite' });
+
+// Query
+const notes = await stack.query({
+  filter: { typeId: 'com.example.myapp/note@1', tags: ['favourite'] },
+  sort: { field: 'createdAt', direction: 'desc' },
+});
+
+// Tear down when done
+await stack.flush();
+await stack.close();
+```
+
+## Core concepts
+
+### Records
+
+The fundamental unit of data. Every record has:
+
+- A **Crockford base-32 ID** — time-sortable, human-readable, URL-safe
+- A **type** — defined by the app that created it
+- **Content** — a JSON object validated against the type's schema
+- Optional: `parentId`, `entityId`, `appId`, `permissions`, `associations`
+
+### Types
+
+Types define the schema for a record's content. They are identified by a namespaced, versioned string:
+
+```
+com.example.myapp/note@1
+```
+
+The app author controls the namespace. Two stacks running the same app have the same type IDs and can interop.
+
+### Associations
+
+Tags, attachments, and relationships are unified under a single model:
+
+```ts
+{ kind: 'tag',          label: 'favourite' }
+{ kind: 'attachment',   label: 'avatar',   fileId: '...', mimeType: 'image/png' }
+{ kind: 'relationship', label: 'reply-to', recordId: '...' }
+```
+
+### Migrations
+
+Types can evolve over time. Register migration functions between adjacent versions and the library composes them into chains automatically:
+
+```ts
+await stack.defineType(
+  'com.example.myapp/note@2',
+  'Note',
+  { text: { kind: 'text', required: true }, title: { kind: 'string' } },
+  { migratesFrom: 'com.example.myapp/note@1' },
+);
+
+stack.registerMigration({
+  from: 'com.example.myapp/note@1',
+  to: 'com.example.myapp/note@2',
+  migrate: (content) => ({ ...content, title: '' }),
+});
+```
+
+Migration is **lazy** — records are migrated in memory on read and committed to disk on the next update. Use `stack.migrateAll()` to commit eagerly.
+
+## License
+
+[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — public domain.
+
+## Monorepo
+
+Part of [haverstack/core](https://github.com/haverstack/core).

package/dist/id.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Stack — ID Generation
+ * -------------------------------------------------------
+ * Crockford base-32 encoded IDs. Time-sortable, human-readable,
+ * and URL-safe. Unique within a stack.
+ *
+ * Format: 9-char timestamp prefix + 3-char random suffix = 12 chars total.
+ *
+ * Ported from https://github.com/cuibonobo/cuibonobo.com/blob/main/src/lib/id.ts
+ * with crypto.randomInt replaced by crypto.getRandomValues for
+ * runtime-agnostic compatibility (Node, browser, Deno, etc.)
+ */
+export declare const BASE: number;
+export declare const RAND_SUFFIX_LENGTH = 3;
+export declare class IdGenerationError extends Error {
+    constructor(message?: string);
+}
+export declare class IdGenerationOverflowError extends IdGenerationError {
+    constructor(message?: string);
+}
+export declare const crockford32Encode: (n: number) => string;
+export declare const crockford32Decode: (s: string) => number;
+export declare const _setLastNowId: (chars: string) => void;
+export declare const _setLastRandChars: (chars: string) => void;
+/**
+ * Generate a new Stack record ID.
+ *
+ * IDs are time-sortable: lexicographic order matches creation order.
+ * Same-millisecond IDs are monotonically incremented to preserve order
+ * and avoid collisions. Throws IdGenerationOverflowError if more than
+ * BASE^RAND_SUFFIX_LENGTH (32^3 = 32,768) IDs are generated in one millisecond.
+ *
+ * @param timestamp - Override the timestamp (ms since epoch). Defaults to Date.now().
+ */
+export declare const generateId: (timestamp?: number) => string;
+//# sourceMappingURL=id.d.ts.map

package/dist/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,eAAO,MAAM,IAAI,QAAoB,CAAC;AAGtC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAUpC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAK;CAIzB;AAED,qBAAa,yBAA0B,SAAQ,iBAAiB;gBAClD,OAAO,SAAK;CAIzB;AAMD,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAiB7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAe7C,CAAC;AAoCF,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,IAK7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,IAKjD,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,YAAW,MAAmB,KAAG,MAQ3D,CAAC"}

package/dist/id.js

@@ -0,0 +1,129 @@
+/**
+ * Stack — ID Generation
+ * -------------------------------------------------------
+ * Crockford base-32 encoded IDs. Time-sortable, human-readable,
+ * and URL-safe. Unique within a stack.
+ *
+ * Format: 9-char timestamp prefix + 3-char random suffix = 12 chars total.
+ *
+ * Ported from https://github.com/cuibonobo/cuibonobo.com/blob/main/src/lib/id.ts
+ * with crypto.randomInt replaced by crypto.getRandomValues for
+ * runtime-agnostic compatibility (Node, browser, Deno, etc.)
+ */
+const CHARACTERS = '0123456789abcdefghjkmnpqrstvwxyz';
+export const BASE = CHARACTERS.length;
+const MIN_TIMESTAMP_LENGTH = 9;
+export const RAND_SUFFIX_LENGTH = 3;
+// Module-level state for monotonicity within the same millisecond
+let lastNowId = '';
+let lastRandChars = '';
+// -------------------------------------------------------
+// Errors
+// -------------------------------------------------------
+export class IdGenerationError extends Error {
+    constructor(message = '') {
+        super(message || 'An ID could not be generated.');
+        this.name = 'IdGenerationError';
+    }
+}
+export class IdGenerationOverflowError extends IdGenerationError {
+    constructor(message = '') {
+        super(message || 'Too many IDs have been generated in the same millisecond.');
+        this.name = 'IdGenerationOverflowError';
+    }
+}
+// -------------------------------------------------------
+// Encoding / decoding
+// -------------------------------------------------------
+export const crockford32Encode = (n) => {
+    if (n < 0) {
+        throw new RangeError('Not defined for negative numbers!');
+    }
+    n = Math.floor(n);
+    if (n === 0) {
+        return CHARACTERS[0];
+    }
+    let result = '';
+    while (n > 0) {
+        result = CHARACTERS[n % BASE] + result;
+        n = Math.floor(n / BASE);
+    }
+    return result;
+};
+export const crockford32Decode = (s) => {
+    if (s.length === 0) {
+        throw new RangeError('String must not be empty!');
+    }
+    s = s.toLowerCase();
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const val = CHARACTERS.indexOf(s[s.length - i - 1]);
+        if (val < 0) {
+            throw new RangeError(`Undefined character in string: "${s[s.length - i - 1]}"`);
+        }
+        n += val * Math.pow(BASE, i);
+    }
+    return n;
+};
+// -------------------------------------------------------
+// Internal helpers
+// -------------------------------------------------------
+const pad = (chars, length) => chars.padStart(length, CHARACTERS[0]);
+/**
+ * Generate a random suffix using Web Crypto API.
+ * Works in Node (>=19), browsers, Deno, and Bun.
+ */
+const generateRandChars = () => {
+    const max = Math.pow(BASE, RAND_SUFFIX_LENGTH) - 1;
+    const arr = new Uint32Array(1);
+    // Rejection sampling to avoid modulo bias
+    let value;
+    do {
+        crypto.getRandomValues(arr);
+        value = arr[0];
+    } while (value > Math.floor(0xffffffff / max) * max);
+    return pad(crockford32Encode(value % max), RAND_SUFFIX_LENGTH);
+};
+const incrementRandChars = (randChars) => {
+    const next = crockford32Encode(crockford32Decode(randChars) + 1);
+    if (next.length > RAND_SUFFIX_LENGTH) {
+        throw new IdGenerationOverflowError();
+    }
+    return pad(next, RAND_SUFFIX_LENGTH);
+};
+// -------------------------------------------------------
+// Test hooks (package-private)
+// -------------------------------------------------------
+export const _setLastNowId = (chars) => {
+    if (chars.length < MIN_TIMESTAMP_LENGTH) {
+        throw new RangeError(`lastNowId must have at least ${MIN_TIMESTAMP_LENGTH} characters.`);
+    }
+    lastNowId = chars;
+};
+export const _setLastRandChars = (chars) => {
+    if (chars.length !== RAND_SUFFIX_LENGTH) {
+        throw new RangeError(`lastRandChars must have exactly ${RAND_SUFFIX_LENGTH} characters.`);
+    }
+    lastRandChars = chars;
+};
+// -------------------------------------------------------
+// Public API
+// -------------------------------------------------------
+/**
+ * Generate a new Stack record ID.
+ *
+ * IDs are time-sortable: lexicographic order matches creation order.
+ * Same-millisecond IDs are monotonically incremented to preserve order
+ * and avoid collisions. Throws IdGenerationOverflowError if more than
+ * BASE^RAND_SUFFIX_LENGTH (32^3 = 32,768) IDs are generated in one millisecond.
+ *
+ * @param timestamp - Override the timestamp (ms since epoch). Defaults to Date.now().
+ */
+export const generateId = (timestamp = Date.now()) => {
+    const nowId = pad(crockford32Encode(timestamp), MIN_TIMESTAMP_LENGTH);
+    const randChars = nowId !== lastNowId ? generateRandChars() : incrementRandChars(lastRandChars);
+    lastNowId = nowId;
+    lastRandChars = randChars;
+    return nowId + randChars;
+};
+//# sourceMappingURL=id.js.map

package/dist/id.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @haverstack/core
+ * -------------------------------------------------------
+ * Core library for Haverstack — portable personal data stack.
+ *
+ * Exports the Stack class, all types, and utility functions.
+ * Storage adapters are published as separate packages:
+ *   @haverstack/adapter-sqlite
+ */
+export { Stack, StackValidationError, StackMigrationError } from './stack.js';
+export type { CreateRecordOptions, GetRecordOptions, DeleteRecordOptions } from './stack.js';
+export type { RecordId, TypeId, FileId, StackRecord, RecordVersion, StackType, TypeSchema, FieldDef, ScalarFieldDef, ArrayFieldDef, ObjectFieldDef, ScalarFieldKind, Association, TagAssociation, AttachmentAssociation, RelationshipAssociation, Permission, StackQuery, RecordFilter, QuerySort, QueryResult, DateRange, Migration, MigrationFn, AdapterCapabilities, StackAdapter, EntityContent, AppContent, GroupContent, } from './types.js';
+export { SYSTEM_TYPES } from './types.js';
+export { generateId, crockford32Encode, crockford32Decode } from './id.js';
+export { hashSchema, isCompatible, parseTypeId, buildTypeId } from './schema.js';
+export { validateContent, isValid } from './validate.js';
+export type { ValidationError } from './validate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC9E,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAG7F,YAAY,EACV,QAAQ,EACR,MAAM,EACN,MAAM,EACN,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,SAAS,EACT,WAAW,EACX,SAAS,EACT,SAAS,EACT,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @haverstack/core
+ * -------------------------------------------------------
+ * Core library for Haverstack — portable personal data stack.
+ *
+ * Exports the Stack class, all types, and utility functions.
+ * Storage adapters are published as separate packages:
+ *   @haverstack/adapter-sqlite
+ */
+// Core class
+export { Stack, StackValidationError, StackMigrationError } from './stack.js';
+export { SYSTEM_TYPES } from './types.js';
+// Utilities
+export { generateId, crockford32Encode, crockford32Decode } from './id.js';
+export { hashSchema, isCompatible, parseTypeId, buildTypeId } from './schema.js';
+export { validateContent, isValid } from './validate.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,aAAa;AACb,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAoC9E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,YAAY;AACZ,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Stack — Schema Utilities
+ * -------------------------------------------------------
+ * Schema hashing and type compatibility checks.
+ *
+ * Hashing produces a stable SHA-256 fingerprint of a TypeSchema
+ * by canonicalizing it first (alphabetical keys, minified JSON).
+ * This is used for drift detection — not type identity, which is
+ * the namespaced ID controlled by the app author.
+ */
+import type { TypeSchema } from './types.js';
+/**
+ * Compute a stable SHA-256 hash of a TypeSchema.
+ * Used for drift detection — if two records share a typeId but their
+ * schemas hash differently, the schema was mutated without a version bump.
+ */
+export declare const hashSchema: (schema: TypeSchema) => Promise<string>;
+/**
+ * Check whether a candidate schema satisfies a required schema.
+ *
+ * A candidate is compatible if it contains all *required* fields from
+ * the required schema with matching kinds. Optional fields in the
+ * required schema are ignored. Array and object fields are matched
+ * shallowly — only the top-level kind is checked.
+ *
+ * Apps that need precise type matching should compare typeIds directly.
+ * isCompatible() is for duck-typed consumption across types.
+ */
+export declare const isCompatible: (candidateSchema: TypeSchema, requiredSchema: TypeSchema) => boolean;
+/**
+ * Parse a versioned TypeId into its base and version components.
+ * e.g. "com.example.myapp/note@2" → { baseId: "com.example.myapp/note", version: 2 }
+ * Returns null if the ID is not versioned (e.g. system types at definition time).
+ */
+export declare const parseTypeId: (typeId: string) => {
+    baseId: string;
+    version: number;
+} | null;
+/**
+ * Build a versioned TypeId from a base ID and version number.
+ * e.g. ("com.example.myapp/note", 2) → "com.example.myapp/note@2"
+ */
+export declare const buildTypeId: (baseId: string, version: number) => string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AA8CvD;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAU,QAAQ,UAAU,KAAG,OAAO,CAAC,MAAM,CAMnE,CAAC;AAMF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,iBAAiB,UAAU,EAAE,gBAAgB,UAAU,KAAG,OAMtF,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAIlF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAAgC,CAAC"}

package/dist/schema.js

@@ -0,0 +1,100 @@
+/**
+ * Stack — Schema Utilities
+ * -------------------------------------------------------
+ * Schema hashing and type compatibility checks.
+ *
+ * Hashing produces a stable SHA-256 fingerprint of a TypeSchema
+ * by canonicalizing it first (alphabetical keys, minified JSON).
+ * This is used for drift detection — not type identity, which is
+ * the namespaced ID controlled by the app author.
+ */
+// -------------------------------------------------------
+// Canonical schema serialization
+// -------------------------------------------------------
+/**
+ * Recursively sort all object keys alphabetically so that two schemas
+ * with the same fields in different orders produce the same hash.
+ */
+const canonicalizeFieldDef = (def) => {
+    if (def.kind === 'array') {
+        return {
+            items: canonicalizeFieldDef(def.items),
+            kind: def.kind,
+            ...(def.required !== undefined && { required: def.required }),
+        };
+    }
+    if (def.kind === 'object') {
+        return {
+            kind: def.kind,
+            properties: canonicalizeSchema(def.properties),
+            ...(def.required !== undefined && { required: def.required }),
+        };
+    }
+    // Scalar
+    return {
+        kind: def.kind,
+        ...(def.required !== undefined && { required: def.required }),
+    };
+};
+const canonicalizeSchema = (schema) => {
+    return Object.fromEntries(Object.keys(schema)
+        .sort()
+        .map((key) => [key, canonicalizeFieldDef(schema[key])]));
+};
+// -------------------------------------------------------
+// Hashing
+// -------------------------------------------------------
+/**
+ * Compute a stable SHA-256 hash of a TypeSchema.
+ * Used for drift detection — if two records share a typeId but their
+ * schemas hash differently, the schema was mutated without a version bump.
+ */
+export const hashSchema = async (schema) => {
+    const canonical = JSON.stringify(canonicalizeSchema(schema));
+    const buffer = new TextEncoder().encode(canonical);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+};
+// -------------------------------------------------------
+// Type compatibility
+// -------------------------------------------------------
+/**
+ * Check whether a candidate schema satisfies a required schema.
+ *
+ * A candidate is compatible if it contains all *required* fields from
+ * the required schema with matching kinds. Optional fields in the
+ * required schema are ignored. Array and object fields are matched
+ * shallowly — only the top-level kind is checked.
+ *
+ * Apps that need precise type matching should compare typeIds directly.
+ * isCompatible() is for duck-typed consumption across types.
+ */
+export const isCompatible = (candidateSchema, requiredSchema) => {
+    return Object.entries(requiredSchema).every(([key, def]) => {
+        if (!def.required)
+            return true;
+        const field = candidateSchema[key];
+        return field !== undefined && field.kind === def.kind;
+    });
+};
+// -------------------------------------------------------
+// Type ID parsing
+// -------------------------------------------------------
+/**
+ * Parse a versioned TypeId into its base and version components.
+ * e.g. "com.example.myapp/note@2" → { baseId: "com.example.myapp/note", version: 2 }
+ * Returns null if the ID is not versioned (e.g. system types at definition time).
+ */
+export const parseTypeId = (typeId) => {
+    const match = typeId.match(/^(.+)@(\d+)$/);
+    if (!match)
+        return null;
+    return { baseId: match[1], version: parseInt(match[2], 10) };
+};
+/**
+ * Build a versioned TypeId from a base ID and version number.
+ * e.g. ("com.example.myapp/note", 2) → "com.example.myapp/note@2"
+ */
+export const buildTypeId = (baseId, version) => `${baseId}@${version}`;
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

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