{
    "comment": "Reference-by-example worldlet for the Puck object format. Class definitions (records a-f) use the whole-hash form that puck.uno/class opts into \u2014 class identity at the record's top level alongside the definition's properties. Instance records (g-v) use the explicit {bucket, stack} shape from the objects spec. Comments on each record say what to notice. The 'files' / 'file_chunks' dicts use the file-record shape from the worldlets spec, not the object shape.",
    "format": "worldlet/1.0",
    "records": {
        "a": {
            "comment": "Class definition in whole-hash form: class='puck.uno/class' plus the definition's properties (name, description, fields) at the record's top level \u2014 the shorthand puck.uno/class opts into. The 'name' field shows the hash-of-typed-sub-fields shape with 'of' setting the default sub-field class, 'default' applying sub-field-wide settings, and 'fields' overriding per sub-field.",
            "class": "puck.uno/class",
            "name": "starfleet.com/person",
            "description": "A person.",
            "fields": {
                "name": {
                    "class": "hash",
                    "of": "string",
                    "required": true,
                    "default": {
                        "collapse": true
                    },
                    "description": "Surname + given + optional middle name.",
                    "fields": {
                        "surname": {
                            "required": true
                        },
                        "given": {},
                        "middle": {}
                    }
                },
                "dob": {
                    "class": "timestamp"
                }
            }
        },
        "b": {
            "comment": "Class definition with inherits (single-parent here; array form accepts multiple), a methods block, params as a hash of option-hashes (not a positional array), and two method-body forms: Caspian source strings (salute, tea_earl_grey_hot) plus the nested-method namespace beverage.nested.{tea_earl_grey_hot, coffee_black}.",
            "class": "puck.uno/class",
            "name": "starfleet.com/officer",
            "description": "A commissioned Starfleet officer.",
            "inherits": [
                "starfleet.com/person"
            ],
            "fields": {
                "rank": {
                    "class": "string",
                    "required": true
                },
                "serial": {
                    "class": "string",
                    "required": true,
                    "unique": true
                },
                "active": {
                    "class": "boolean",
                    "default": true
                }
            },
            "methods": {
                "beverage": {
                    "nested": {
                        "tea_earl_grey_hot": {
                            "description": "Picard's preferred way to interface with a replicator.",
                            "params": {
                                "variety": {
                                    "class": "string",
                                    "required": true,
                                    "description": "What kind of tea to order."
                                },
                                "temperature": {
                                    "class": "string",
                                    "required": true,
                                    "description": "Serving temperature (typically 'hot')."
                                }
                            },
                            "returns": {
                                "class": "string",
                                "description": "Beverage description, or null if the replicator refuses."
                            },
                            "body": "if ($variety == 'coffee')\n    puts 'Replicator: That order requires Captain Janeway.'\n    return (null)\nend\n\nputs 'Tea. ' + $variety + '. ' + $temperature + '.'\nputs '*replicator hums in satisfaction*'\nreturn ('A steaming cup of ' + $variety + ' appears.')"
                        },
                        "coffee_black": {
                            "description": "Janeway's preferred way to interface with a replicator. Strictly black; rejects modifiers.",
                            "params": {
                                "style": {
                                    "class": "string",
                                    "required": true,
                                    "description": "Coffee style. Janeway accepts only 'black'."
                                },
                                "temperature": {
                                    "class": "string",
                                    "default": "hot",
                                    "description": "Serving temperature. Defaults to 'hot' because Janeway."
                                }
                            },
                            "returns": {
                                "class": "string",
                                "description": "Beverage description, or null if the replicator refuses."
                            },
                            "body": "if ($style != 'black')\n    puts 'Replicator: The captain takes it black.'\n    return (null)\nend\n\nputs 'Coffee. ' + $style + '. ' + $temperature + '.'\nputs '*Janeway sighs contentedly*'\nreturn ('A steaming cup of coffee appears.')"
                        }
                    }
                },
                "salute": {
                    "description": "Render a verbal salute from this officer toward someone of a given rank.",
                    "params": {
                        "name": {
                            "class": "string",
                            "required": true,
                            "description": "Name of the person being saluted."
                        },
                        "rank": {
                            "class": "string",
                            "required": true,
                            "description": "Rank of the person being saluted."
                        },
                        "attention": {
                            "class": "boolean",
                            "default": false,
                            "description": "Call attention before the salute."
                        },
                        "style": {
                            "class": "string",
                            "one_of": [
                                "formal",
                                "casual"
                            ],
                            "default": "formal"
                        },
                        "props": {
                            "splat": true,
                            "description": "Any extra context the renderer may use."
                        }
                    },
                    "returns": {
                        "class": "string",
                        "description": "The rendered salute line."
                    },
                    "body": "puts $rank + ' ' + $name + ', sir!'"
                }
            }
        },
        "c": {
            "comment": "Class definition with field-level uniqueness (unique: true on registry) and a method body in CaspJ tree form rather than Caspian source string.",
            "class": "puck.uno/class",
            "name": "starfleet.com/starship",
            "description": "A Starfleet starship.",
            "fields": {
                "registry": {
                    "class": "string",
                    "required": true,
                    "unique": true,
                    "description": "Hull registry (e.g. NCC-1701)."
                },
                "name": {
                    "class": "string",
                    "required": true,
                    "description": "Display name (Enterprise, Defiant)."
                },
                "classification": {
                    "class": "string",
                    "required": true,
                    "description": "Spaceframe class (Constitution, Galaxy, Sovereign)."
                },
                "launched": {
                    "class": "timestamp",
                    "description": "Commissioning date."
                },
                "active": {
                    "class": "boolean",
                    "default": true,
                    "description": "Currently in service."
                }
            },
            "methods": {
                "hail": {
                    "description": "Open a channel to the target.",
                    "params": {
                        "target": {
                            "class": "string",
                            "required": true,
                            "description": "Target UNS (ship, station, or planet)."
                        },
                        "priority": {
                            "class": "string",
                            "one_of": [
                                "routine",
                                "priority",
                                "emergency"
                            ],
                            "default": "routine"
                        },
                        "subject": {
                            "class": "string",
                            "description": "Optional subject line for the hail."
                        }
                    },
                    "returns": {
                        "class": "boolean",
                        "description": "True iff the channel opened."
                    },
                    "body": [
                        [
                            {
                                "bwc": "puts"
                            },
                            [
                                {
                                    "value": "Hailing "
                                },
                                "+",
                                {
                                    "var": "target"
                                }
                            ]
                        ]
                    ]
                }
            }
        },
        "d": {
            "comment": "Class definition with a one_of enum constraint on classification and a method body that reads instance variables via {ivar: ...} in its CaspJ tree.",
            "class": "puck.uno/class",
            "name": "federation.com/planet",
            "description": "A planet recognized by the Federation cartographic registry.",
            "fields": {
                "name": {
                    "class": "string",
                    "required": true,
                    "description": "Common name (Earth, Vulcan, Risa)."
                },
                "designation": {
                    "class": "string",
                    "required": true,
                    "unique": true,
                    "description": "Astronomical designation (Sol III, 40 Eridani A II)."
                },
                "system": {
                    "class": "string",
                    "required": true,
                    "description": "Parent star system."
                },
                "classification": {
                    "class": "string",
                    "one_of": [
                        "M",
                        "L",
                        "K",
                        "Y",
                        "D",
                        "J",
                        "T"
                    ],
                    "description": "Habitability class."
                },
                "federation_member": {
                    "class": "boolean",
                    "default": false,
                    "description": "Member of the United Federation of Planets."
                }
            },
            "methods": {
                "describe": {
                    "description": "Return a one-line summary of the planet.",
                    "params": {},
                    "returns": {
                        "class": "string"
                    },
                    "body": [
                        [
                            {
                                "bwc": "puts"
                            },
                            [
                                {
                                    "ivar": "name"
                                },
                                "+",
                                [
                                    {
                                        "value": " ("
                                    },
                                    "+",
                                    [
                                        {
                                            "ivar": "designation"
                                        },
                                        "+",
                                        {
                                            "value": ")"
                                        }
                                    ]
                                ]
                            ]
                        ]
                    ]
                }
            }
        },
        "e": {
            "comment": "Class definition with a class-level multi-field unique constraint via the 'uniques' array. Each inner array is a tuple whose combined values must be unique across all records of the class; here (ship, voyage_number).",
            "class": "puck.uno/class",
            "name": "starfleet.com/voyage",
            "description": "A discrete deployment of a Starfleet ship.",
            "fields": {
                "ship": {
                    "class": "string",
                    "required": true,
                    "description": "Registry of the ship on this voyage."
                },
                "voyage_number": {
                    "class": "number",
                    "required": true,
                    "description": "Sequential number within the ship's history."
                },
                "start_date": {
                    "class": "timestamp",
                    "required": true
                },
                "end_date": {
                    "class": "timestamp",
                    "description": "Absent while the voyage is still under way."
                },
                "mission_type": {
                    "class": "string",
                    "one_of": [
                        "exploration",
                        "diplomatic",
                        "patrol",
                        "rescue",
                        "combat"
                    ],
                    "default": "exploration"
                }
            },
            "uniques": [
                [
                    "ship",
                    "voyage_number"
                ]
            ]
        },
        "f": {
            "comment": "Class definition with reference fields (class puck.uno/reference + target UNS \u2014 typed pointers between record kinds) and the deliberately-preserved 'unqiues' typo.",
            "class": "puck.uno/class",
            "name": "starfleet.com/assignment",
            "fields": {
                "person": {
                    "class": "puck.uno/reference",
                    "target": "starfleet.com/person",
                    "required": true
                },
                "starship": {
                    "class": "puck.uno/reference",
                    "target": "starfleet.com/starship",
                    "required": true
                },
                "status": {
                    "class": "string",
                    "required": true
                }
            },
            "unqiues": [
                [
                    "person",
                    "starship"
                ]
            ]
        },
        "g": {
            "comment": "Instance record in the {bucket, stack} shape: instance data in bucket, class identity (starfleet.com/officer) in the stack's 'a' platter under shadow. The 'photo' field is itself an inline object using the same {bucket, stack} shape \u2014 a puck.uno/reference/file value pointing at the photo file in the worldlet's files dict.",
            "bucket": {
                "name": {
                    "surname": "Picard",
                    "given": "Jean-Luc"
                },
                "dob": "2305-07-13T00:00:00Z",
                "rank": "Captain",
                "serial": "SP-937-215",
                "active": true,
                "photo": {
                    "bucket": {
                        "value": "f1a2b3c4-0001-0001-0001-000000000001"
                    },
                    "stack": {
                        "shadow": {},
                        "a": {
                            "class": "puck.uno/reference/file"
                        }
                    }
                }
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/officer"
                }
            }
        },
        "h": {
            "comment": "Same instance shape as Picard, with a 'middle' field present on the name hash.",
            "bucket": {
                "name": {
                    "surname": "Riker",
                    "given": "William",
                    "middle": "Thomas"
                },
                "dob": "2335-08-19T00:00:00Z",
                "rank": "Commander",
                "serial": "SC-231-427",
                "active": true,
                "photo": "f1a2b3c4-0002-0002-0002-000000000002"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/officer"
                }
            }
        },
        "i": {
            "comment": "Same instance shape; only 'surname' on the name hash (given and middle are absent since they aren't required on the person class).",
            "bucket": {
                "name": {
                    "surname": "Data"
                },
                "dob": "2338-02-02T00:00:00Z",
                "rank": "Lieutenant Commander",
                "serial": "SC-499-235",
                "active": true,
                "photo": "f1a2b3c4-0003-0003-0003-000000000003"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/officer"
                }
            }
        },
        "j": {
            "comment": "Standard officer instance.",
            "bucket": {
                "name": {
                    "surname": "Janeway",
                    "given": "Kathryn"
                },
                "dob": "2335-05-20T00:00:00Z",
                "rank": "Captain",
                "serial": "SC-957-398",
                "active": true,
                "photo": "f1a2b3c4-0004-0004-0004-000000000004"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/officer"
                }
            }
        },
        "k": {
            "comment": "Starship instance.",
            "bucket": {
                "registry": "NCC-1701-D",
                "name": "Enterprise",
                "classification": "Galaxy",
                "launched": "2363-10-04T00:00:00Z",
                "active": true
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/starship"
                }
            }
        },
        "l": {
            "comment": "Another starship \u2014 no notable structural variation.",
            "bucket": {
                "registry": "NX-74205",
                "name": "Defiant",
                "classification": "Defiant",
                "launched": "2370-01-01T00:00:00Z",
                "active": true
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/starship"
                }
            }
        },
        "m": {
            "comment": "Standard instance: bucket holds the ship data; the 'a' platter in the stack carries the class identity (starfleet.com/starship). This is the canonical shape for any instance record under the new spec.",
            "bucket": {
                "registry": "NCC-74656",
                "name": "Voyager",
                "classification": "Intrepid",
                "launched": "2371-01-01T00:00:00Z",
                "active": true
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/starship"
                }
            }
        },
        "n": {
            "comment": "Planet instance. The 'classification' value is one of the strings declared in the planet class's one_of enum.",
            "bucket": {
                "name": "Earth",
                "designation": "Sol III",
                "system": "Sol",
                "classification": "M",
                "federation_member": true
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "federation.com/planet"
                }
            }
        },
        "o": {
            "comment": "Another planet; same one_of constraint applies.",
            "bucket": {
                "name": "Vulcan",
                "designation": "40 Eridani A II",
                "system": "40 Eridani A",
                "classification": "M",
                "federation_member": true
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "federation.com/planet"
                }
            }
        },
        "p": {
            "comment": "Another planet.",
            "bucket": {
                "name": "Risa",
                "designation": "Epsilon Ceti B II",
                "system": "Epsilon Ceti B",
                "classification": "M",
                "federation_member": true
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "federation.com/planet"
                }
            }
        },
        "q": {
            "comment": "Voyage instance \u2014 pairs with r to demonstrate the multi-field unique constraint declared on the voyage class. Here (ship='NCC-1701-D', voyage_number=1).",
            "bucket": {
                "ship": "NCC-1701-D",
                "voyage_number": 1,
                "start_date": "2364-10-04T00:00:00Z",
                "mission_type": "exploration"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/voyage"
                }
            }
        },
        "r": {
            "comment": "Second voyage record with voyage_number=1 again. Allowed because it pairs with a different ship (NCC-74656); the uniqueness is on the tuple, not on voyage_number alone.",
            "bucket": {
                "ship": "NCC-74656",
                "voyage_number": 1,
                "start_date": "2371-01-01T00:00:00Z",
                "mission_type": "exploration"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/voyage"
                }
            }
        },
        "s": {
            "comment": "Assignment instance. The 'person' and 'starship' field values are puck.uno/reference strings keyed to other records in this worldlet ('g' = Picard, 'k' = Enterprise-D).",
            "bucket": {
                "person": "g",
                "starship": "k",
                "status": "commanding officer"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/assignment"
                }
            }
        },
        "t": {
            "comment": "Another assignment \u2014 same shape.",
            "bucket": {
                "person": "h",
                "starship": "k",
                "status": "first officer"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/assignment"
                }
            }
        },
        "u": {
            "comment": "Another assignment.",
            "bucket": {
                "person": "i",
                "starship": "k",
                "status": "operations officer"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/assignment"
                }
            }
        },
        "v": {
            "comment": "Final assignment. Note the targets are 'j' and 'm' \u2014 Janeway commanding Voyager.",
            "bucket": {
                "person": "j",
                "starship": "m",
                "status": "commanding officer"
            },
            "stack": {
                "shadow": {},
                "a": {
                    "class": "starfleet.com/assignment"
                }
            }
        }
    },
    "files": {
        "f1a2b3c4-0001-0001-0001-000000000001": {
            "comment": "files dict entry. Required fields: 'sha256' (SHA-256 hex digest of the assembled content, for integrity) and 'mime' (a hash with 'type' and 'encoding'). PNG image with base64-encoded chunks.",
            "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "mime": {
                "type": "image/png",
                "encoding": "base64"
            }
        },
        "f1a2b3c4-0002-0002-0002-000000000002": {
            "comment": "Another PNG file; same shape.",
            "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "mime": {
                "type": "image/png",
                "encoding": "base64"
            }
        },
        "f1a2b3c4-0003-0003-0003-000000000003": {
            "comment": "Another PNG file; same shape.",
            "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "mime": {
                "type": "image/png",
                "encoding": "base64"
            }
        },
        "f1a2b3c4-0004-0004-0004-000000000004": {
            "comment": "Another PNG file; same shape.",
            "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "mime": {
                "type": "image/png",
                "encoding": "base64"
            }
        },
        "f1a2b3c4-0005-0005-0005-000000000005": {
            "comment": "Two variations from the photo files above: optional 'created_at' timestamp, and mime.encoding='utf-8' (chunk data holds raw text directly, not base64). Also: this file is standalone \u2014 no record references it. Files don't have to be attached to records.",
            "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
            "created_at": "2364-01-04T11:00:00Z",
            "mime": {
                "type": "text/plain",
                "encoding": "utf-8"
            }
        }
    },
    "file_chunks": {
        "c1d2e3f4-0001-0001-0001-000000000001": {
            "comment": "file_chunks dict entry. 'file' is the parent file's key; 'index' is the 0-based chunk position (chunks reassemble in ascending index order); 'last': true marks the final chunk (exactly one per file \u2014 positive confirmation the file finished writing); 'data' carries the chunk content encoded per the parent file's mime.encoding (base64 here).",
            "file": "f1a2b3c4-0001-0001-0001-000000000001",
            "index": 0,
            "last": true,
            "data": "iVBORw0KGgoAAAANSUhEUgAAA..."
        },
        "c1d2e3f4-0002-0002-0002-000000000002": {
            "file": "f1a2b3c4-0002-0002-0002-000000000002",
            "index": 0,
            "last": true,
            "data": "iVBORw0KGgoAAAANSUhEUgAAB..."
        },
        "c1d2e3f4-0003-0003-0003-000000000003": {
            "file": "f1a2b3c4-0003-0003-0003-000000000003",
            "index": 0,
            "last": true,
            "data": "iVBORw0KGgoAAAANSUhEUgAAC..."
        },
        "c1d2e3f4-0004-0004-0004-000000000004": {
            "file": "f1a2b3c4-0004-0004-0004-000000000004",
            "index": 0,
            "last": true,
            "data": "iVBORw0KGgoAAAANSUhEUgAAD..."
        },
        "c1d2e3f4-0005-0005-0005-000000000005": {
            "comment": "Same chunk shape, but 'data' is raw utf-8 text instead of base64, per the parent file's mime.encoding='utf-8'. Single-chunk file \u2014 index 0, last true.",
            "file": "f1a2b3c4-0005-0005-0005-000000000005",
            "index": 0,
            "last": true,
            "data": "Stardate 41174.3. The Enterprise is en route to Deneb IV..."
        }
    }
}